chore: bump version to 11.0.1

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

.claude-plugin/plugin.json

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

.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,6 +1,7 @@
 datasets/
 node_modules/
 dist/
+**/_tree-sitter/
 *.log
 .DS_Store
 .env
@@ -18,7 +19,6 @@ plugin/data.backup/
 package-lock.json
 bun.lock
 private/
-datasets/
 Auto Run Docs/
 
 # Generated UI files (built from viewer-template.html)
@@ -28,12 +28,13 @@ src/ui/viewer.html
 .mcp.json
 .cursor/
 
-# Prevent literal tilde directories (path validation bug artifacts)
-~*/
-
-# Prevent other malformed path directories
-http*/
-https*/
-
 # Ignore WebStorm project files (for dinosaur IDE users)
 .idea/
+
+.claude-octopus/
+.claude/session-intent.md
+.claude/session-plan.md
+.octo/
+
+# Local contribution analysis (not part of upstream)
+CONTRIB_NOTES.md

.markdownlint.json

@@ -0,0 +1,3 @@
+{
+  "MD013": false
+}

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

.plan/npx-distribution.md

@@ -0,0 +1,736 @@
+# Plan: NPX Distribution + Universal IDE/CLI Coverage for claude-mem
+
+## Problem
+
+1. **Installation is slow and fragile**: Current install clones the full git repo, runs `npm install`, and builds from source. The npm package already ships pre-built artifacts.
+
+2. **IDE coverage is limited**: claude-mem only supports Claude Code (plugin) and Cursor (hooks installer). The AI coding tools landscape has exploded — Gemini CLI (95k stars), OpenCode (110k stars), Windsurf (~1M users), Codex CLI, Antigravity, Goose, Crush, Copilot CLI, and more all support extensibility.
+
+## Key Insights
+
+- **npm package already has everything**: `plugin/` directory ships pre-built. No git clone or build needed.
+- **Transcript watcher already exists**: `src/services/transcripts/` has a fully built schema-based JSONL tailer. It just needs schemas for more tools.
+- **3 integration tiers exist**: (1) Hook/plugin-based (Claude Code, Gemini CLI, OpenCode, Windsurf, Codex CLI, OpenClaw), (2) MCP-based (Cursor, Copilot CLI, Antigravity, Goose, Crush, Roo Code), (3) Transcript-based (anything with structured log files).
+- **OpenClaw plugin already built**: Full plugin at `openclaw/src/index.ts` (1000+ lines). Needs to be wired into the npx installer.
+- **Gemini CLI is architecturally near-identical to Claude Code**: 11 lifecycle hooks, JSON via stdin/stdout, exit code 0/2 convention, `GEMINI.md` context files, `~/.gemini/settings.json`. This is the easiest high-value integration.
+- **OpenCode has the richest plugin system**: 20+ hook events across 12 categories, JS/TS plugin modules, custom tool creation, MCP support. 110k stars — largest open-source AI CLI.
+- **`npx skills` by Vercel supports 41 agents** — proving the multi-IDE installer UX works. Their agent detection pattern (check if config dir exists) is the right model.
+- **All IDEs share a single worker on port 37777**: One worker serves all integrations. Session source (which IDE) is tracked via the `source` field in hook payloads. No per-IDE worker instances.
+- **This npx CLI fully replaces the old `claude-mem-installer`**: Not a supplement — the complete replacement.
+
+## Solution
+
+`npx claude-mem` becomes a unified CLI: install, configure any IDE, manage the worker, search memory.
+
+```
+npx claude-mem                          # Interactive install + IDE selection
+npx claude-mem install                  # Same as above
+npx claude-mem install --ide windsurf   # Direct IDE setup
+npx claude-mem start / stop / status    # Worker management
+npx claude-mem search <query>           # Search memory from terminal
+npx claude-mem transcript watch         # Start transcript watcher
+```
+
+## Platform Support
+
+**Windows, macOS, and Linux are all first-class targets.** Platform-specific considerations:
+
+- **Config paths**: Use `os.homedir()` and `path.join()` everywhere — never hardcode `/` or `~`
+- **Shebangs**: `#!/usr/bin/env node` for the CLI entry point (cross-platform via Node)
+- **Bun detection**: Check `PATH`, common install locations per platform (`%USERPROFILE%\.bun\bin\bun.exe` on Windows, `~/.bun/bin/bun` on Unix)
+- **File permissions**: `fs.chmod` is a no-op on Windows; don't gate on it
+- **Process management**: Worker start/stop uses signals on Unix, taskkill on Windows — match existing `worker-service.ts` patterns
+- **VS Code paths**: `~/Library/Application Support/Code/` (macOS), `~/.config/Code/` (Linux), `%APPDATA%/Code/` (Windows)
+- **Shell config**: `.bashrc`/`.zshrc` on Unix, PowerShell profile on Windows (for PATH modifications if needed)
+
+---
+
+## Phase 0: Research Findings
+
+### IDE Integration Tiers
+
+**Tier 1 — Native Hook/Plugin Systems** (highest fidelity, real-time capture):
+
+| Tool | Hooks | Config Location | Context Injection | Stars/Users |
+|------|-------|----------------|-------------------|-------------|
+| Claude Code | 5 lifecycle hooks | `~/.claude/settings.json` | CLAUDE.md, plugins | ~25% market |
+| Gemini CLI | 11 lifecycle hooks | `~/.gemini/settings.json` | GEMINI.md | ~95k stars |
+| OpenCode | 20+ event hooks + plugin SDK | `~/.config/opencode/opencode.json` | AGENTS.md + rules dirs | ~110k stars |
+| Windsurf | 11 Cascade hooks | `.windsurf/hooks.json` | `.windsurf/rules/*.md` | ~1M users |
+| Codex CLI | `notify` hook | `~/.codex/config.toml` | `.codex/AGENTS.md`, MCP | Growing (OpenAI) |
+| OpenClaw | 8 event hooks + plugin SDK | `~/.openclaw/openclaw.json` | MEMORY.md sync | ~196k stars |
+
+**Tier 2 — MCP Integration** (tool-based, search + context injection):
+
+| Tool | MCP Support | Config Location | Context Injection |
+|------|------------|----------------|-------------------|
+| Cursor | First-class | `.cursor/mcp.json` | `.cursor/rules/*.mdc` |
+| Copilot CLI | First-class (default MCP) | `~/.copilot/config` | `.github/copilot-instructions.md` |
+| Antigravity | First-class + MCP Store | `~/.gemini/antigravity/mcp_config.json` | `.agent/rules/`, GEMINI.md |
+| Goose | Native MCP (co-developed protocol) | `~/.config/goose/config.yaml` | MCP context |
+| Crush | MCP + Skills | JSON config (charm.land schema) | Skills system |
+| Roo Code | First-class | `.roo/` | `.roo/rules/*.md`, `AGENTS.md` |
+| Warp | MCP + Warp Drive | `WARP.md` + Warp Drive UI | `WARP.md` |
+
+**Tier 3 — Transcript File Watching** (passive, file-based):
+
+| Tool | Transcript Location | Format |
+|------|-------------------|--------|
+| Claude Code | `~/.claude/projects/<proj>/<session>.jsonl` | JSONL |
+| Codex CLI | `~/.codex/sessions/**/*.jsonl` | JSONL |
+| Gemini CLI | `~/.gemini/tmp/<hash>/chats/` | JSON |
+| OpenCode | `.opencode/` (SQLite) | SQLite — needs export |
+
+### What claude-mem Already Has
+
+| Component | Status | Location |
+|-----------|--------|----------|
+| Claude Code plugin | Complete | `plugin/hooks/hooks.json` |
+| Cursor hooks installer | Complete | `src/services/integrations/CursorHooksInstaller.ts` |
+| Platform adapters | Claude Code + Cursor + raw | `src/cli/adapters/` |
+| Transcript watcher | Complete (schema-based JSONL) | `src/services/transcripts/` |
+| Codex transcript schema | Sample exists | `src/services/transcripts/config.ts` |
+| OpenClaw plugin | Complete (1000+ lines) | `openclaw/src/index.ts` |
+| MCP server | Complete | `plugin/scripts/mcp-server.cjs` |
+| Gemini CLI support | Not started | — |
+| OpenCode support | Not started | — |
+| Windsurf support | Not started | — |
+
+### Patterns to Copy
+
+- **Agent detection from `npx skills`** (`vercel-labs/skills/src/agents.ts`): Check if config directory exists
+- **Existing installer logic** (`installer/src/steps/install.ts:29-83`): registerMarketplace, registerPlugin, enablePluginInClaudeSettings — **extract shared logic** from existing installer into reusable modules (DRY with the new CLI)
+- **Bun resolution** (`plugin/scripts/bun-runner.js`): PATH lookup + common locations per platform
+- **CursorHooksInstaller** (`src/services/integrations/CursorHooksInstaller.ts`): Reference implementation for IDE hooks installation
+
+---
+
+## Phase 1: NPX CLI Entry Point
+
+### What to implement
+
+1. **Add `bin` field to `package.json`**:
+   ```json
+   "bin": {
+     "claude-mem": "./dist/cli/index.js"
+   }
+   ```
+
+2. **Create `src/npx-cli/index.ts`** — a Node.js CLI router (NOT Bun) with command categories:
+
+   **Install commands** (pure Node.js, no Bun required):
+   - `npx claude-mem` or `npx claude-mem install` → interactive install (IDE multi-select)
+   - `npx claude-mem install --ide <name>` → direct IDE setup (only for implemented IDEs; unimplemented ones error with "Support for <name> coming soon")
+   - `npx claude-mem update` → update to latest version
+   - `npx claude-mem uninstall` → remove plugin and IDE configs
+   - `npx claude-mem version` → print version
+
+   **Runtime commands** (delegate to Bun via installed plugin):
+   - `npx claude-mem start` → spawns `bun worker-service.cjs start`
+   - `npx claude-mem stop` → spawns `bun worker-service.cjs stop`
+   - `npx claude-mem restart` → spawns `bun worker-service.cjs restart`
+   - `npx claude-mem status` → spawns `bun worker-service.cjs status`
+   - `npx claude-mem search <query>` → hits `GET http://localhost:37777/api/search?q=<query>`
+   - `npx claude-mem transcript watch` → starts transcript watcher
+
+   **Runtime commands must check for installation first**: If plugin directory doesn't exist at `~/.claude/plugins/marketplaces/thedotmack/`, print "claude-mem is not installed. Run: npx claude-mem install" and exit.
+
+3. **The install flow** (fully replaces git clone + build):
+   - Detect the npm package's own location (`import.meta.url` or `__dirname`)
+   - Copy `plugin/` from the npm package to `~/.claude/plugins/marketplaces/thedotmack/`
+   - Copy `plugin/` to `~/.claude/plugins/cache/thedotmack/claude-mem/<version>/`
+   - Register marketplace in `~/.claude/plugins/known_marketplaces.json`
+   - Register plugin in `~/.claude/plugins/installed_plugins.json`
+   - Enable in `~/.claude/settings.json`
+   - Run `npm install` in the marketplace dir (for `@chroma-core/default-embed` — native ONNX binaries, can't be bundled)
+   - Trigger smart-install.js for Bun/uv setup
+   - Run IDE-specific setup for each selected IDE
+
+4. **Interactive IDE selection** (auto-detect + prompt):
+   - Auto-detect installed IDEs by checking config directories
+   - Present multi-select with detected IDEs pre-selected
+   - Detection map:
+     - Claude Code: `~/.claude/` exists
+     - Gemini CLI: `~/.gemini/` exists
+     - OpenCode: `~/.config/opencode/` exists OR `opencode` in PATH
+     - OpenClaw: `~/.openclaw/` exists
+     - Windsurf: `~/.codeium/windsurf/` exists
+     - Codex CLI: `~/.codex/` exists
+     - Cursor: `~/.cursor/` exists
+     - Copilot CLI: `copilot` in PATH (it's a CLI tool, not a config dir)
+     - Antigravity: `~/.gemini/antigravity/` exists
+     - Goose: `~/.config/goose/` exists OR `goose` in PATH
+     - Crush: `crush` in PATH
+     - Roo Code: check for VS Code extension directory containing `roo-code`
+     - Warp: `~/.warp/` exists OR `warp` in PATH
+
+5. **The runtime command routing**:
+   - Locate the installed plugin directory
+   - Find Bun binary (same logic as `bun-runner.js`, platform-aware)
+   - Spawn `bun worker-service.cjs <command>` and pipe stdio through
+   - For `search`: HTTP request to running worker
+
+### Patterns to follow
+
+- `installer/src/steps/install.ts:29-83` for marketplace registration — **extract to shared module**
+- `plugin/scripts/bun-runner.js` for Bun resolution
+- `vercel-labs/skills/src/agents.ts` for IDE auto-detection pattern
+
+### Verification
+
+- `npx claude-mem install` copies plugin to correct directories on macOS, Linux, and Windows
+- Auto-detection finds installed IDEs
+- `npx claude-mem start/stop/status` work after install
+- `npx claude-mem search "test"` returns results
+- `npx claude-mem start` before install prints helpful error message
+- `npx claude-mem update` and `npx claude-mem uninstall` work correctly
+- `npx claude-mem version` prints version
+
+### Anti-patterns
+
+- Do NOT require Bun for install commands — pure Node.js
+- Do NOT clone the git repo
+- Do NOT build from source at install time
+- Do NOT depend on `bun:sqlite` in the CLI entry point
+
+---
+
+## Phase 2: Build Pipeline Integration
+
+### What to implement
+
+1. **Add CLI build step to `scripts/build-hooks.js`**:
+   - Compile `src/npx-cli/index.ts` → `dist/cli/index.js`
+   - Bundle `@clack/prompts` and `picocolors` into the output (self-contained)
+   - Shebang: `#!/usr/bin/env node`
+   - Set executable permissions (no-op on Windows, that's fine)
+
+2. **Move `@clack/prompts` and `picocolors`** to main package.json as dev dependencies (bundled by esbuild into dist/cli/index.js)
+
+3. **Verify `package.json` `files` field**: Currently `["dist", "plugin"]`. `dist/cli/index.js` is already included since it's under `dist/`. No change needed.
+
+4. **Update `prepublishOnly`** to ensure CLI is built before npm publish (already covered — `npm run build` calls `build-hooks.js`)
+
+5. **Pre-build OpenClaw plugin**: Add an esbuild step that compiles `openclaw/src/index.ts` → `openclaw/dist/index.js` so it ships ready-to-use. No `tsc` at install time.
+
+6. **Add `openclaw/dist/` to `package.json` `files` field** (or add `openclaw` if the whole directory should ship)
+
+### Verification
+
+- `npm run build` produces `dist/cli/index.js` with correct shebang
+- `npm run build` produces `openclaw/dist/index.js` pre-built
+- `npm pack` includes both `dist/cli/index.js` and `openclaw/dist/`
+- `node dist/cli/index.js --help` works without Bun
+- Package size is reasonable (check with `npm pack --dry-run`)
+
+---
+
+## Phase 3: Gemini CLI Integration (Tier 1 — Hook-Based)
+
+**Why first among new IDEs**: Near-identical architecture to Claude Code. 11 lifecycle hooks with JSON stdin/stdout, same exit code conventions (0=success, 2=block), `GEMINI.md` context files. 95k GitHub stars. Lowest effort, highest confidence.
+
+### Gemini CLI Hook Events
+
+| Event | Map to claude-mem | Use |
+|-------|-------------------|-----|
+| `SessionStart` | `session-init` | Start tracking session |
+| `BeforeAgent` | `user-prompt` | Capture user prompt |
+| `AfterAgent` | `observation` | Capture full agent response |
+| `BeforeTool` | — | Skip (pre-execution, no result yet) |
+| `AfterTool` | `observation` | Capture tool name + input + response |
+| `BeforeModel` | — | Skip (too low-level, LLM request details) |
+| `AfterModel` | — | Skip (raw LLM response, redundant with AfterAgent) |
+| `BeforeToolSelection` | — | Skip (internal planning step) |
+| `PreCompress` | `summary` | Trigger summary before context compression |
+| `Notification` | — | Skip (system alerts, not session data) |
+| `SessionEnd` | `session-end` | Finalize session |
+
+**Mapped**: 5 of 11 events. **Skipped**: 6 events that are either too low-level (BeforeModel/AfterModel), pre-execution (BeforeTool, BeforeToolSelection), or system-level (Notification).
+
+### Verified Stdin Payload Schemas (from `packages/core/src/hooks/types.ts`)
+
+**Base input (all hooks receive):**
+```typescript
+{ session_id: string, transcript_path: string, cwd: string, hook_event_name: string, timestamp: string }
+```
+
+**Event-specific fields:**
+| Event | Additional Fields |
+|-------|-------------------|
+| `SessionStart` | `source: "startup" \| "resume" \| "clear"` |
+| `SessionEnd` | `reason: "exit" \| "clear" \| "logout" \| "prompt_input_exit" \| "other"` |
+| `BeforeAgent` | `prompt: string` |
+| `AfterAgent` | `prompt: string, prompt_response: string, stop_hook_active: boolean` |
+| `BeforeTool` | `tool_name: string, tool_input: Record<string, unknown>, mcp_context?: McpToolContext, original_request_name?: string` |
+| `AfterTool` | `tool_name: string, tool_input: Record<string, unknown>, tool_response: Record<string, unknown>, mcp_context?: McpToolContext` |
+| `PreCompress` | `trigger: "auto" \| "manual"` |
+| `Notification` | `notification_type: "ToolPermission", message: string, details: Record<string, unknown>` |
+
+**Output (all hooks can return):**
+```typescript
+{ continue?: boolean, stopReason?: string, suppressOutput?: boolean, systemMessage?: string, decision?: "allow" | "deny" | "block" | "approve" | "ask", reason?: string, hookSpecificOutput?: Record<string, unknown> }
+```
+
+**Advisory (non-blocking) hooks:** SessionStart, SessionEnd, PreCompress, Notification — `continue` and `decision` fields are ignored.
+
+**Environment variables provided:** `GEMINI_PROJECT_DIR`, `GEMINI_SESSION_ID`, `GEMINI_CWD`, `CLAUDE_PROJECT_DIR` (compat alias)
+
+### What to implement
+
+1. **Create Gemini CLI platform adapter** at `src/cli/adapters/gemini-cli.ts`:
+   - Normalize Gemini CLI's hook JSON to `NormalizedHookInput`
+   - Base fields always present: `session_id`, `transcript_path`, `cwd`, `hook_event_name`, `timestamp`
+   - Map per event:
+     - `SessionStart`: `source` → session init metadata
+     - `BeforeAgent`: `prompt` → user prompt text
+     - `AfterAgent`: `prompt` + `prompt_response` → full conversation turn
+     - `AfterTool`: `tool_name` + `tool_input` + `tool_response` → observation
+     - `PreCompress`: `trigger` → summary trigger
+     - `SessionEnd`: `reason` → session finalization
+
+2. **Create Gemini CLI hooks installer** at `src/services/integrations/GeminiCliHooksInstaller.ts`:
+   - Write hooks to `~/.gemini/settings.json` under the `hooks` key
+   - Must **merge** with existing settings (read → parse → deep merge → write)
+   - Hook config format (verified against official docs):
+     ```json
+     {
+       "hooks": {
+         "AfterTool": [{
+           "matcher": "*",
+           "hooks": [{ "name": "claude-mem", "type": "command", "command": "<path-to-hook-script>", "timeout": 5000 }]
+         }]
+       }
+     }
+     ```
+   - Note: `matcher` uses regex for tool events, exact string for lifecycle events. `"*"` or `""` matches all.
+   - Hook groups support `sequential: boolean` (default false = parallel execution)
+   - Security: Project-level hooks are fingerprinted — if name/command changes, user is warned
+   - Context injection via `~/.gemini/GEMINI.md` (append claude-mem section with `<claude-mem-context>` tags, same pattern as CLAUDE.md)
+   - Settings hierarchy: project `.gemini/settings.json` > user `~/.gemini/settings.json` > system `/etc/gemini-cli/settings.json`
+
+3. **Register `gemini-cli` in `getPlatformAdapter()`** at `src/cli/adapters/index.ts`
+
+4. **Add Gemini CLI to installer IDE selection**
+
+### Verification
+
+- `npx claude-mem install --ide gemini-cli` merges hooks into `~/.gemini/settings.json`
+- Gemini CLI sessions are captured by the worker
+- `AfterTool` events produce observations with correct `tool_name`, `tool_input`, `tool_response`
+- `GEMINI.md` gets claude-mem context section
+- Existing Gemini CLI settings are preserved (merge, not overwrite)
+- Verify `session_id` from base input is used for session tracking
+
+### Anti-patterns
+
+- Do NOT overwrite `~/.gemini/settings.json` — must deep merge
+- Do NOT map all 11 events — the 6 skipped events would produce noise, not signal
+- Do NOT use `type: "runtime"` — that's for internal extensions only; use `type: "command"`
+- Advisory hooks (SessionStart, SessionEnd, PreCompress, Notification) cannot block — don't set `decision` or `continue` fields on them
+
+---
+
+## Phase 4: OpenCode Integration (Tier 1 — Plugin-Based)
+
+**Why next**: 110k stars, richest plugin ecosystem. OpenCode plugins are JS/TS modules auto-loaded from plugin directories. OpenCode also has a Claude Code compatibility fallback (reads `~/.claude/CLAUDE.md` if no global `AGENTS.md` exists, controllable via `OPENCODE_DISABLE_CLAUDE_CODE_PROMPT=1`).
+
+### Verified Plugin API (from `packages/plugin/src/index.ts`)
+
+**Plugin signature:**
+```typescript
+import { type Plugin, tool } from "@opencode-ai/plugin"
+
+export const ClaudeMemPlugin: Plugin = async (ctx) => {
+  // ctx: { client, project, directory, worktree, serverUrl, $ }
+  return { /* hooks object */ }
+}
+```
+
+**PluginInput type (6 properties, not 4):**
+```typescript
+type PluginInput = {
+  client: ReturnType<typeof createOpencodeClient>  // OpenCode SDK client
+  project: Project                                   // Current project info
+  directory: string                                  // Current working directory
+  worktree: string                                   // Git worktree path
+  serverUrl: URL                                     // Server URL
+  $: BunShell                                        // Bun shell API
+}
+```
+
+**Two hook mechanisms (important distinction):**
+
+1. **Direct interceptor hooks** — keys on the returned `Hooks` object, receive `(input, output)` allowing mutation:
+   - `tool.execute.before`: `(input: { tool, sessionID, callID }, output: { args })`
+   - `tool.execute.after`: `(input: { tool, sessionID, callID, args }, output: { title, output, metadata })`
+   - `shell.env`, `chat.message`, `chat.params`, `chat.headers`, `permission.ask`, `command.execute.before`
+   - Experimental: `experimental.session.compacting`, `experimental.chat.messages.transform`, `experimental.chat.system.transform`
+
+2. **Bus event catch-all** — generic `event` hook, receives `{ event }` where `event.type` is the event name:
+   - `session.created`, `session.compacted`, `session.deleted`, `session.idle`, `session.error`, `session.status`, `session.updated`, `session.diff`
+   - `message.updated`, `message.part.updated`, `message.part.removed`, `message.removed`
+   - `file.edited`, `file.watcher.updated`
+   - `command.executed`, `todo.updated`, `installation.updated`, `server.connected`
+   - `permission.asked`, `permission.replied`
+   - `lsp.client.diagnostics`, `lsp.updated`
+   - `tui.prompt.append`, `tui.command.execute`, `tui.toast.show`
+   - Total: **27 bus events** across **12 categories**
+
+**Custom tool registration (CORRECTED — name is the key, not positional arg):**
+```typescript
+return {
+  tool: {
+    claude_mem_search: tool({
+      description: "Search claude-mem memory database",
+      args: { query: tool.schema.string() },
+      async execute(args, context) {
+        // context: { sessionID, messageID, agent, directory, worktree, abort, metadata, ask }
+        const response = await fetch(`http://localhost:37777/api/search?q=${encodeURIComponent(args.query)}`)
+        return await response.text()
+      },
+    }),
+  },
+}
+```
+
+### What to implement
+
+1. **Create OpenCode plugin** at `src/integrations/opencode-plugin/index.ts`:
+   - Export a `Plugin` function receiving full `PluginInput` context
+   - Use **direct interceptor** `tool.execute.after` for tool observation capture (gives `tool`, `args`, `output`)
+   - Use **bus event catch-all** `event` for session lifecycle:
+
+   | Mechanism | Event | Map to claude-mem |
+   |-----------|-------|-------------------|
+   | interceptor | `tool.execute.after` | `observation` (tool name + args + output) |
+   | bus event | `session.created` | `session-init` |
+   | bus event | `message.updated` | `observation` (assistant messages) |
+   | bus event | `session.compacted` | `summary` |
+   | bus event | `file.edited` | `observation` (file changes) |
+   | bus event | `session.deleted` | `session-end` |
+
+   - Register `claude_mem_search` custom tool using correct `tool({ description, args, execute })` API
+   - Hit `localhost:37777` API endpoints from the plugin
+
+2. **Build the plugin** in the esbuild pipeline → `dist/opencode-plugin/index.js`
+
+3. **Create OpenCode setup in installer** (two options, prefer file-based):
+   - **Option A (file-based):** Copy plugin to `~/.config/opencode/plugins/claude-mem.ts` (auto-loaded at startup)
+   - **Option B (npm-based):** Add to `~/.config/opencode/opencode.json` under `"plugin"` array: `["claude-mem"]`
+   - Config also supports JSONC (`opencode.jsonc`) and legacy `config.json`
+   - Context injection: Append to `~/.config/opencode/AGENTS.md` (or create it) with `<claude-mem-context>` tags
+   - Additional context via `"instructions"` config key (supports file paths, globs, remote URLs)
+
+4. **Add OpenCode to installer IDE selection**
+
+### OpenCode Verification
+
+- `npx claude-mem install --ide opencode` registers the plugin (file or npm)
+- OpenCode loads the plugin on next session
+- `tool.execute.after` interceptor produces observations with `tool`, `args`, `output`
+- Bus events (`session.created`, `session.deleted`) handle session lifecycle
+- `claude_mem_search` custom tool works in OpenCode sessions
+- Context is injected via AGENTS.md
+
+### OpenCode Anti-patterns
+
+- Do NOT try to use OpenCode's `session.diff` for full capture — it's a summary diff, not raw data
+- Do NOT use `tool('name', schema, handler)` — wrong signature. Name is the key in the `tool:{}` map
+- Do NOT assume bus events have the same `(input, output)` mutation pattern — they only receive `{ event }`
+- OpenCode plugins run in Bun — the plugin CAN use Bun APIs (unlike the npx CLI itself)
+- Do NOT hardcode `~/.config/opencode/` — respect `OPENCODE_CONFIG_DIR` env var if set
+
+---
+
+## Phase 5: Windsurf Integration (Tier 1 — Hook-Based)
+
+**Why next**: 11 Cascade hooks, ~1M users. Hook architecture uses JSON stdin with a consistent envelope format.
+
+### Verified Windsurf Hook Events (from docs.windsurf.com/windsurf/cascade/hooks)
+
+**Naming pattern**: `pre_`/`post_` prefix + 5 action categories, plus 2 standalone post-only events.
+
+| Event | Can Block? | Map to claude-mem | Use |
+|-------|-----------|-------------------|-----|
+| `pre_user_prompt` | Yes | `session-init` + `context` | Start session, inject context |
+| `pre_read_code` | Yes | — | Skip (pre-execution, can block file reads) |
+| `post_read_code` | No | — | Skip (too noisy, file reads are frequent) |
+| `pre_write_code` | Yes | — | Skip (pre-execution, can block writes) |
+| `post_write_code` | No | `observation` | Code generation |
+| `pre_run_command` | Yes | — | Skip (pre-execution, can block commands) |
+| `post_run_command` | No | `observation` | Shell command execution |
+| `pre_mcp_tool_use` | Yes | — | Skip (pre-execution, can block MCP calls) |
+| `post_mcp_tool_use` | No | `observation` | MCP tool results |
+| `post_cascade_response` | No | `observation` | Full AI response |
+| `post_setup_worktree` | No | — | Skip (informational) |
+
+**Mapped**: 5 of 11 events (all post-action). **Skipped**: 4 pre-hooks (blocking-capable, pre-execution) + 2 low-value post-hooks.
+
+### Verified Stdin Payload Schema
+
+**Common envelope (all hooks):**
+```json
+{
+  "agent_action_name": "string",
+  "trajectory_id": "string",
+  "execution_id": "string",
+  "timestamp": "ISO 8601 string",
+  "tool_info": { /* event-specific payload */ }
+}
+```
+
+**Event-specific `tool_info` payloads:**
+
+| Event | `tool_info` fields |
+|-------|-------------------|
+| `pre_user_prompt` | `{ user_prompt: string }` |
+| `pre_read_code` / `post_read_code` | `{ file_path: string }` |
+| `pre_write_code` / `post_write_code` | `{ file_path: string, edits: [{ old_string: string, new_string: string }] }` |
+| `pre_run_command` / `post_run_command` | `{ command_line: string, cwd: string }` |
+| `pre_mcp_tool_use` | `{ mcp_server_name: string, mcp_tool_name: string, mcp_tool_arguments: {} }` |
+| `post_mcp_tool_use` | `{ mcp_server_name: string, mcp_tool_name: string, mcp_tool_arguments: {}, mcp_result: string }` |
+| `post_cascade_response` | `{ response: string }` (markdown) |
+| `post_setup_worktree` | `{ worktree_path: string, root_workspace_path: string }` |
+
+**Exit codes:** `0` = success, `2` = block (pre-hooks only; stderr shown to agent), any other = non-blocking warning.
+
+### What to implement
+
+1. **Create Windsurf platform adapter** at `src/cli/adapters/windsurf.ts`:
+   - Normalize Windsurf's hook input format to `NormalizedHookInput`
+   - Common envelope: `agent_action_name`, `trajectory_id`, `execution_id`, `timestamp`, `tool_info`
+   - Map: `trajectory_id` → `sessionId`, `tool_info` fields per event type
+   - For `post_write_code`: `tool_info.file_path` + `tool_info.edits` → file change observation
+   - For `post_run_command`: `tool_info.command_line` + `tool_info.cwd` → command observation
+   - For `post_mcp_tool_use`: `tool_info.mcp_tool_name` + `tool_info.mcp_tool_arguments` + `tool_info.mcp_result` → tool observation
+   - For `post_cascade_response`: `tool_info.response` → full AI response observation
+
+2. **Create Windsurf hooks installer** at `src/services/integrations/WindsurfHooksInstaller.ts`:
+   - Write hooks to `~/.codeium/windsurf/hooks.json` (user-level, for global coverage)
+   - Per-workspace override at `.windsurf/hooks.json` if user chooses workspace-level install
+   - Config format (verified):
+     ```json
+     {
+       "hooks": {
+         "post_write_code": [{
+           "command": "<path-to-hook-script>",
+           "show_output": false,
+           "working_directory": "<optional>"
+         }]
+       }
+     }
+     ```
+   - Note: Tilde expansion (`~`) is NOT supported in `working_directory` — use absolute paths
+   - Merge order: cloud → system → user → workspace (all hooks at all levels execute)
+   - Context injection via `.windsurf/rules/claude-mem-context.md` (workspace-level; Windsurf rules are workspace-scoped)
+   - Rule limits: 6,000 chars per file, 12,000 chars total across all rules
+
+3. **Register `windsurf` in `getPlatformAdapter()`** at `src/cli/adapters/index.ts`
+
+4. **Add Windsurf to installer IDE selection**
+
+### Windsurf Verification
+
+- `npx claude-mem install --ide windsurf` creates hooks config at `~/.codeium/windsurf/hooks.json`
+- Windsurf sessions are captured by the worker via post-action hooks
+- `trajectory_id` is used as session identifier
+- Context is injected via `.windsurf/rules/claude-mem-context.md` (under 6K char limit)
+- Existing hooks.json is preserved (merge, not overwrite)
+
+### Windsurf Anti-patterns
+
+- Do NOT use fabricated event names (`post_search_code`, `post_lint_code`, `on_error`, `pre_tool_execution`) — they don't exist
+- Do NOT assume Windsurf's stdin JSON matches Claude Code's — it uses `tool_info` envelope, not flat fields
+- Do NOT use tilde (`~`) in `working_directory` — not supported, use absolute paths
+- Do NOT exceed 6K chars in the context rule file — Windsurf truncates beyond that
+- Pre-hooks can block actions (exit 2) — only use post-hooks for observation capture
+
+---
+
+## Phase 6: Codex CLI Integration (Tier 1 — Hook + Transcript)
+
+### Dedup strategy
+
+Codex has both a `notify` hook (real-time) and transcript files (complete history). Use **transcript watching only** — it's more complete and avoids the complexity of dual capture paths. The `notify` hook is a simpler mechanism that doesn't provide enough granularity to justify maintaining two integration paths. If transcript watching proves insufficient, add the notify hook later.
+
+### What to implement
+
+1. **Create Codex transcript schema** — the sample in `src/services/transcripts/config.ts` is already production-quality. Verify against current Codex CLI JSONL format and update if needed.
+
+2. **Create Codex setup in installer**:
+   - Write transcript-watch config to `~/.claude-mem/transcript-watch.json`
+   - Set up watch for `~/.codex/sessions/**/*.jsonl` using existing CODEX_SAMPLE_SCHEMA
+   - Context injection via `.codex/AGENTS.md` (Codex reads this natively)
+   - Must merge with existing `config.toml` if it exists (read → parse → merge → write)
+
+3. **Add Codex CLI to installer IDE selection**
+
+### Verification
+
+- `npx claude-mem install --ide codex` creates transcript watch config
+- Codex sessions appear in claude-mem database
+- `AGENTS.md` updated with context after sessions
+- Existing `config.toml` is preserved
+
+---
+
+## Phase 7: OpenClaw Integration (Tier 1 — Plugin-Based)
+
+**Plugin is already fully built** at `openclaw/src/index.ts` (~1000 lines). Has event hooks, SSE observation feed, MEMORY.md sync, slash commands. Only wiring into the installer is needed.
+
+### What to implement
+
+1. **Wire OpenClaw into the npx installer**:
+   - Detect `~/.openclaw/` directory
+   - Copy pre-built plugin from `openclaw/dist/` (built in Phase 2) to OpenClaw plugins location
+   - Register in `~/.openclaw/openclaw.json` under `plugins.claude-mem`
+   - Configure worker port, project name, syncMemoryFile
+   - Optionally prompt for observation feed setup (channel type + target ID)
+
+2. **Add OpenClaw to IDE selection TUI** with hint about messaging channel support
+
+### Verification
+
+- `npx claude-mem install --ide openclaw` registers the plugin
+- OpenClaw gateway loads the plugin on restart
+- Observations are recorded from OpenClaw sessions
+- MEMORY.md syncs to agent workspaces
+
+### Anti-patterns
+
+- Do NOT rebuild the OpenClaw plugin from source at install time — it ships pre-built from Phase 2
+- Do NOT modify the plugin's event handling — it's battle-tested
+
+---
+
+## Phase 8: MCP-Based Integrations (Tier 2)
+
+**These get the MCP server for free** — it already exists at `plugin/scripts/mcp-server.cjs`. The installer just needs to write the right config files per IDE.
+
+MCP-only integrations provide: search tools + context injection. They do NOT capture transcripts or tool usage in real-time.
+
+### What to implement
+
+1. **Copilot CLI MCP setup**:
+   - Write MCP config to `~/.copilot/config` (merge, not overwrite)
+   - Context injection: `.github/copilot-instructions.md`
+   - Detection: `copilot` command in PATH
+
+2. **Antigravity MCP setup**:
+   - Write MCP config to `~/.gemini/antigravity/mcp_config.json` (merge, not overwrite)
+   - Context injection: `~/.gemini/GEMINI.md` (shared with Gemini CLI) and/or `.agent/rules/claude-mem-context.md`
+   - Detection: `~/.gemini/antigravity/` exists
+   - Note: Antigravity has NO hook system — MCP is the only integration path
+
+3. **Goose MCP setup**:
+   - Write MCP config to `~/.config/goose/config.yaml` (YAML merge — use a lightweight YAML parser or write the block manually if config doesn't exist)
+   - Detection: `~/.config/goose/` exists OR `goose` in PATH
+   - Note: Goose co-developed MCP with Anthropic, so MCP support is excellent
+
+4. **Crush MCP setup**:
+   - Write MCP config to Crush's JSON config
+   - Detection: `crush` in PATH
+
+5. **Roo Code MCP setup**:
+   - Write MCP config to `.roo/` or workspace settings
+   - Context injection: `.roo/rules/claude-mem-context.md`
+   - Detection: Check for VS Code extension directory containing `roo-code`
+
+6. **Warp MCP setup**:
+   - Warp uses `WARP.md` in project root for context injection (similar to CLAUDE.md)
+   - MCP servers configured via Warp Drive UI, but also via config files
+   - Detection: `~/.warp/` exists OR `warp` in PATH
+   - Note: Warp is a terminal replacement (~26k stars), not just a CLI tool — multi-agent orchestration with management UI
+
+7. **For each**: Add to installer IDE detection and selection
+
+### Config merging strategy
+
+JSON configs: Read → parse → deep merge → write back. YAML configs (Goose): If file exists, read and append the MCP block. If not, create from template. Avoid pulling in a full YAML parser library — write the MCP block as a string append with proper indentation if the format is predictable.
+
+### Verification
+
+- Each IDE can search claude-mem via MCP tools
+- Context files are written to IDE-specific locations
+- Existing configs are preserved
+
+### Anti-patterns
+
+- MCP-only integrations do NOT capture transcripts — don't claim "full integration"
+- Do NOT overwrite existing config files — always merge
+- Do NOT add a heavy YAML parser dependency for one integration
+
+---
+
+## Phase 9: Remove Old Installer
+
+This is a **full replacement**, not a deprecation.
+
+### What to implement
+
+1. Remove `claude-mem-installer` npm package (unpublish or mark deprecated with message pointing to `npx claude-mem`)
+2. Update `install/public/install.sh` → redirect to `npx claude-mem`
+3. Remove `installer/` directory from the repository (it's replaced by `src/npx-cli/`)
+4. Update docs site to reflect the new install command
+5. Update README.md install instructions
+
+---
+
+## Phase 10: Final Verification
+
+### All platforms (macOS, Linux, Windows)
+
+1. `npm run build` succeeds, produces `dist/cli/index.js` and `openclaw/dist/index.js`
+2. `node dist/cli/index.js install` works clean (no prior install)
+3. Auto-detects installed IDEs correctly per platform
+4. `npx claude-mem start/stop/status/search` all work
+5. `npx claude-mem update` updates correctly
+6. `npx claude-mem uninstall` cleans up all IDE configs
+7. `npx claude-mem version` prints version
+8. `npx claude-mem start` before install shows helpful error
+9. No Bun dependency at install time
+
+### Per-integration verification
+
+| Integration | Type | Captures Sessions | Search via MCP | Context Injection |
+|-------------|------|-------------------|----------------|-------------------|
+| Claude Code | Plugin | Yes (hooks) | Yes | CLAUDE.md |
+| Gemini CLI | Hooks | Yes (AfterTool, AfterAgent) | Yes (via hook) | GEMINI.md |
+| OpenCode | Plugin | Yes (tool.execute.after, message.updated) | Yes (custom tool) | AGENTS.md / rules |
+| Windsurf | Hooks | Yes (post_cascade_response, etc.) | Yes (via hook) | .windsurf/rules/ |
+| Codex CLI | Transcript | Yes (JSONL watcher) | No (passive only) | .codex/AGENTS.md |
+| OpenClaw | Plugin | Yes (event hooks) | Yes (slash commands) | MEMORY.md |
+| Copilot CLI | MCP | No | Yes | copilot-instructions.md |
+| Antigravity | MCP | No | Yes | .agent/rules/ |
+| Goose | MCP | No | Yes | MCP context |
+| Crush | MCP | No | Yes | Skills |
+| Roo Code | MCP | No | Yes | .roo/rules/ |
+| Warp | MCP | No | Yes | WARP.md |
+
+---
+
+## Priority Order & Impact
+
+| Phase | IDE/Tool | Integration Type | Stars/Users | Effort |
+|-------|----------|-----------------|-------------|--------|
+| 1-2 | (infrastructure) | npx CLI + build pipeline | All users | Medium |
+| 3 | Gemini CLI | Hooks (Tier 1) | ~95k stars | Medium (near-identical to Claude Code) |
+| 4 | OpenCode | Plugin (Tier 1) | ~110k stars | Medium (rich plugin SDK) |
+| 5 | Windsurf | Hooks (Tier 1) | ~1M users | Medium |
+| 6 | Codex CLI | Transcript (Tier 3) | Growing (OpenAI) | Low (schema already exists) |
+| 7 | OpenClaw | Plugin (Tier 1) — pre-built | ~196k stars | Low (wire into installer) |
+| 8 | Copilot CLI, Antigravity, Goose, Crush, Warp, Roo Code | MCP (Tier 2) | 20M+ combined | Low per IDE |
+| 9 | (remove old installer) | — | — | Low |
+| 10 | (final verification) | — | — | Low |
+
+## Out of Scope
+
+- **Removing Bun as runtime dependency**: Worker still requires Bun for `bun:sqlite`. Runtime commands delegate to Bun; install commands don't need it.
+- **JetBrains plugin**: Requires Kotlin/Java development — different ecosystem entirely.
+- **Zed extension**: WASM sandbox limits feasibility.
+- **Neovim/Emacs plugins**: Niche audiences, complex plugin ecosystems (Lua/Elisp). Could be added later via MCP (gptel supports it).
+- **Amazon Q / Kiro**: Amazon Q Developer CLI has been sunsetted in favor of Kiro (proprietary, no public extensibility API yet). Revisit when Kiro opens up.
+- **Aider**: Niche audience, writes Markdown transcripts (not JSONL), would require a markdown parser mode in the watcher. Add if demand materializes.
+- **Continue.dev**: Small user base relative to other MCP tools. Can be added as a Tier 2 MCP integration later if requested.
+- **Toad / Qwen Code / Oh-my-pi**: Too early-stage or too niche. Monitor for growth.
+- **OpenClaw plugin development**: The plugin is already complete. Only installer wiring is in scope.

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

CLAUDE.md

@@ -14,6 +14,10 @@ Claude-mem is a Claude Code plugin providing persistent memory across sessions.
 
 **Search Skill** (`plugin/skills/mem-search/SKILL.md`) - HTTP API for searching past work, auto-invoked when users ask about history
 
+**Planning Skill** (`plugin/skills/make-plan/SKILL.md`) - Orchestrator instructions for creating phased implementation plans with documentation discovery
+
+**Execution Skill** (`plugin/skills/do/SKILL.md`) - Orchestrator instructions for executing phased plans using subagents
+
 **Chroma** (`src/services/sync/ChromaSync.ts`) - Vector embeddings for semantic search
 
 **Viewer UI** (`src/ui/viewer/`) - React interface at http://localhost:37777, built to `plugin/ui/viewer.html`

README.md

@@ -1,13 +1,3 @@
-<p align="center">
-  Official $CMEM Links: 
-  <a href="https://bags.fm/2TsmuYUrsctE57VLckZBYEEzdokUF8j8e1GavekWBAGS">Bags.fm</a> •
-  <a href="https://jup.ag/tokens/2TsmuYUrsctE57VLckZBYEEzdokUF8j8e1GavekWBAGS">Jupiter</a> •
-  <a href="https://photon-sol.tinyastro.io/en/lp/6MzFAkWnac6GSK1EdFX93dZeukGfzrFq4UHWarhGSQyd">Photon</a> •
-  <a href="https://dexscreener.com/solana/6mzfakwnac6gsk1edfx93dzeukgfzrfq4uhwarhgsqyd">DEXScreener</a>
-</p>
-
-<p align="center">Official CA: 2TsmuYUrsctE57VLckZBYEEzdokUF8j8e1GavekWBAGS (on Solana)</p>
-
 <h1 align="center">
   <br>
   <a href="https://github.com/thedotmack/claude-mem">
@@ -84,13 +74,40 @@
 
 <br>
 
-<p align="center">
-  <a href="https://github.com/thedotmack/claude-mem">
-    <picture>
-      <img src="https://raw.githubusercontent.com/thedotmack/claude-mem/main/docs/public/cm-preview.gif" alt="Claude-Mem Preview" width="800">
-    </picture>
-  </a>
-</p>
+<table align="center">
+  <tr>
+    <td align="center">
+      <a href="https://github.com/thedotmack/claude-mem">
+        <picture>
+          <img
+            src="https://raw.githubusercontent.com/thedotmack/claude-mem/main/docs/public/cm-preview.gif"
+            alt="Claude-Mem Preview"
+            width="500"
+          >
+        </picture>
+      </a>
+    </td>
+    <td align="center">
+      <a href="https://www.star-history.com/#thedotmack/claude-mem&Date">
+        <picture>
+          <source
+            media="(prefers-color-scheme: dark)"
+            srcset="https://api.star-history.com/image?repos=thedotmack/claude-mem&type=date&theme=dark&legend=top-left"
+          />
+          <source
+            media="(prefers-color-scheme: light)"
+            srcset="https://api.star-history.com/image?repos=thedotmack/claude-mem&type=date&legend=top-left"
+          />
+          <img
+            alt="Star History Chart"
+            src="https://api.star-history.com/image?repos=thedotmack/claude-mem&type=date&legend=top-left"
+            width="500"
+          />
+        </picture>
+      </a>
+    </td>
+  </tr>
+</table>
 
 <p align="center">
   <a href="#quick-start">Quick Start</a> •
@@ -110,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
 
@@ -154,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
@@ -198,7 +228,7 @@ See [Architecture Overview](https://docs.claude-mem.ai/architecture/overview) fo
 
 ## MCP Search Tools
 
-Claude-Mem provides intelligent memory search through **5 MCP tools** following a token-efficient **3-layer workflow pattern**:
+Claude-Mem provides intelligent memory search through **4 MCP tools** following a token-efficient **3-layer workflow pattern**:
 
 **The 3-Layer Workflow:**
 
@@ -211,7 +241,6 @@ Claude-Mem provides intelligent memory search through **5 MCP tools** following
 - Start with `search` to get an index of results
 - Use `timeline` to see what was happening around specific observations
 - Use `get_observations` to fetch full details for relevant IDs
-- Use `save_memory` to manually store important information
 - **~10x token savings** by filtering before fetching details
 
 **Available MCP Tools:**
@@ -219,8 +248,6 @@ Claude-Mem provides intelligent memory search through **5 MCP tools** following
 1. **`search`** - Search memory index with full-text queries, filters by type/date/project
 2. **`timeline`** - Get chronological context around a specific observation or query
 3. **`get_observations`** - Fetch full observation details by IDs (always batch multiple IDs)
-4. **`save_memory`** - Manually save a memory/observation for semantic search
-5. **`__IMPORTANT`** - Workflow documentation (always visible to Claude)
 
 **Example Usage:**
 
@@ -232,9 +259,6 @@ search(query="authentication bug", type="bugfix", limit=10)
 
 // Step 3: Fetch full details
 get_observations(ids=[123, 456])
-
-// Save important information manually
-save_memory(text="API requires auth header X-API-Key", title="API Auth")
 ```
 
 See [Search Tools Guide](https://docs.claude-mem.ai/usage/search-tools) for detailed examples.
@@ -346,3 +370,9 @@ See the [LICENSE](LICENSE) file for full details.
 ---
 
 **Built with Claude Agent SDK** | **Powered by Claude Code** | **Made with TypeScript**
+
+---
+
+### What About $CMEM?
+
+$CMEM is a solana token created by a 3rd party without Claude-Mem's prior consent, but officially embraced by the creator of Claude-Mem (Alex Newman, @thedotmack). The token acts as a community catalyst for growth and a vehicle for bringing real-time agent data to the developers and knowledge workers that need it most. $CMEM: 2TsmuYUrsctE57VLckZBYEEzdokUF8j8e1GavekWBAGS

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,12 +57,20 @@
           "cursor/openrouter-setup"
         ]
       },
+      {
+        "group": "Gemini CLI Integration",
+        "icon": "terminal",
+        "pages": [
+          "gemini-cli/setup"
+        ]
+      },
       {
         "group": "Best Practices",
         "icon": "lightbulb",
         "pages": [
           "context-engineering",
-          "progressive-disclosure"
+          "progressive-disclosure",
+          "smart-explore-benchmark"
         ]
       },
       {

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

docs/public/openclaw-integration.mdx

@@ -1,6 +1,6 @@
 ---
 title: OpenClaw Integration
-description: Persistent memory for OpenClaw agents — observation recording, MEMORY.md live sync, and real-time observation feeds
+description: Persistent memory for OpenClaw agents — observation recording, system prompt context injection, and real-time observation feeds
 icon: dragon
 ---
 
@@ -9,7 +9,7 @@ icon: dragon
 The OpenClaw plugin gives claude-mem persistent memory to agents running on the [OpenClaw](https://openclaw.ai) gateway. It handles three things:
 
 1. **Observation recording** — Captures tool usage from OpenClaw's embedded runner and sends it to the claude-mem worker for AI processing
-2. **MEMORY.md live sync** — Writes a continuously-updated timeline to each agent's workspace so agents always have context from previous sessions
+2. **System prompt context injection** — Injects the observation timeline into each agent's system prompt via the `before_prompt_build` hook, keeping `MEMORY.md` free for agent-curated memory
 3. **Observation feed** — Streams new observations to messaging channels (Telegram, Discord, Slack, etc.) in real-time via SSE
 
 <Info>
@@ -21,10 +21,11 @@ OpenClaw's embedded runner (`pi-embedded`) calls the Anthropic API directly with
 ```plaintext
 OpenClaw Gateway
   │
-  ├── before_agent_start ──→ Sync MEMORY.md + Init session
-  ├── tool_result_persist ──→ Record observation + Re-sync MEMORY.md
+  ├── before_agent_start ───→ Init session
+  ├── before_prompt_build ──→ Inject context into system prompt
+  ├── tool_result_persist ──→ Record observation
   ├── agent_end ────────────→ Summarize + Complete session
-  └── gateway_start ────────→ Reset session tracking
+  └── gateway_start ────────→ Reset session tracking + context cache
                     │
                     ▼
          Claude-Mem Worker (localhost:37777)
@@ -32,7 +33,7 @@ OpenClaw Gateway
            ├── POST /api/sessions/observations
            ├── POST /api/sessions/summarize
            ├── POST /api/sessions/complete
-           ├── GET  /api/context/inject ──→ MEMORY.md content
+           ├── GET  /api/context/inject ──→ System prompt context
            └── GET  /stream ─────────────→ SSE → Messaging channels
 ```
 
@@ -40,21 +41,15 @@ OpenClaw Gateway
 
 <Steps>
   <Step title="Agent starts (before_agent_start)">
-    When an OpenClaw agent starts, the plugin does two things:
+    When an OpenClaw agent starts, the plugin initializes a session by sending the user prompt to `POST /api/sessions/init` so the worker can create a new session and start processing.
+  </Step>
+  <Step title="Context injected (before_prompt_build)">
+    Before each LLM call, the plugin fetches the observation timeline from the worker's `/api/context/inject` endpoint and returns it as `appendSystemContext`. This injects cross-session context directly into the agent's system prompt without writing any files.
 
-    1. **Syncs MEMORY.md** — Fetches the latest timeline from the worker's `/api/context/inject` endpoint and writes it to `MEMORY.md` in the agent's workspace directory. This gives the agent context from all previous sessions before it starts working.
-
-    2. **Initializes a session** — Sends the user prompt to `POST /api/sessions/init` so the worker can create a new session and start processing.
-
-    Short prompts (under 10 characters) skip session init but still sync MEMORY.md.
+    The context is cached for 60 seconds to avoid re-fetching on every LLM turn within a session.
   </Step>
   <Step title="Tool use recorded (tool_result_persist)">
-    Every time the agent uses a tool (Read, Write, Bash, etc.), the plugin:
-
-    1. **Sends the observation** to `POST /api/sessions/observations` with the tool name, input, and truncated response (max 1000 chars)
-    2. **Re-syncs MEMORY.md** with the latest timeline from the worker
-
-    Both operations are fire-and-forget — they don't block the agent from continuing work. The MEMORY.md file gets progressively richer as the session continues.
+    Every time the agent uses a tool (Read, Write, Bash, etc.), the plugin sends the observation to `POST /api/sessions/observations` with the tool name, input, and truncated response (max 1000 chars). This is fire-and-forget — it doesn't block the agent from continuing work.
 
     Tools prefixed with `memory_` are skipped to avoid recursive recording.
   </Step>
@@ -62,21 +57,18 @@ OpenClaw Gateway
     When the agent completes, the plugin extracts the last assistant message and sends it to `POST /api/sessions/summarize`, then calls `POST /api/sessions/complete` to close the session. Both are fire-and-forget.
   </Step>
   <Step title="Gateway restarts (gateway_start)">
-    Clears all session tracking (session IDs, workspace directory mappings) so agents get fresh state after a gateway restart.
+    Clears all session tracking (session IDs, context cache) so agents get fresh state after a gateway restart.
   </Step>
 </Steps>
 
-### MEMORY.md Live Sync
+### System Prompt Context Injection
 
-The plugin writes a `MEMORY.md` file to each agent's workspace directory containing the full timeline of observations and summaries from previous sessions. This file is updated:
+The plugin injects cross-session observation context into each agent's system prompt via OpenClaw's `before_prompt_build` hook. The content comes from the worker's `GET /api/context/inject?projects=<project>` endpoint, which generates a formatted markdown timeline from the SQLite database.
 
-- On every `before_agent_start` event (agent gets fresh context before starting)
-- On every `tool_result_persist` event (context stays current during the session)
-
-The content comes from the worker's `GET /api/context/inject?projects=<project>` endpoint, which generates a formatted markdown timeline from the SQLite database.
+This approach keeps `MEMORY.md` under the agent's control for curated long-term memory (decisions, preferences, durable facts), while the observation timeline is delivered through the system prompt where it belongs.
 
 <Info>
-MEMORY.md updates are fire-and-forget. They run in the background without blocking the agent. The file reflects whatever the worker has processed so far — it doesn't wait for the current observation to be fully processed before writing.
+Context is cached for 60 seconds per project to avoid re-fetching on every LLM turn. The cache is cleared on gateway restart. Use `syncMemoryFileExclude` to opt specific agents out of context injection entirely.
 </Info>
 
 ### Observation Feed (SSE → Messaging)
@@ -319,7 +311,11 @@ The claude-mem worker service must be running on the same machine as the OpenCla
 </ParamField>
 
 <ParamField body="syncMemoryFile" type="boolean" default={true}>
-  Enable automatic MEMORY.md sync to agent workspaces. Set to `false` if you don't want the plugin writing files to workspace directories.
+  Inject observation context into the agent system prompt via `before_prompt_build` hook. When `true`, agents receive cross-session context automatically. Set to `false` to disable context injection entirely (observations are still recorded).
+</ParamField>
+
+<ParamField body="syncMemoryFileExclude" type="string[]" default={[]}>
+  Agent IDs excluded from automatic context injection. Useful for agents that curate their own memory and don't need the observation timeline (e.g., `["snarf", "debugger"]`). Observations are still recorded for excluded agents — only the context injection is skipped.
 </ParamField>
 
 <ParamField body="workerPort" type="number" default={37777}>
@@ -374,9 +370,9 @@ The plugin uses HTTP calls to the already-running claude-mem worker service rath
 Each OpenClaw agent session gets a unique `contentSessionId` (format: `openclaw-<sessionKey>-<timestamp>`) that maps to a claude-mem session in the worker. The plugin tracks:
 
 - `sessionIds` — Maps OpenClaw session keys to content session IDs
-- `workspaceDirsBySessionKey` — Maps session keys to workspace directories so `tool_result_persist` events can sync MEMORY.md even when the event context doesn't include `workspaceDir`
+- `contextCache` — TTL cache (60s) for context injection responses, keyed by project
 
-Both maps are cleared on `gateway_start`.
+Both are cleared on `gateway_start`.
 
 ## Requirements
 

docs/public/smart-explore-benchmark.mdx

@@ -0,0 +1,196 @@
+---
+title: "Smart Explore Benchmark"
+description: "Token efficiency comparison between AST-based and traditional code exploration"
+---
+
+# Smart Explore Benchmark
+
+Smart Explore uses tree-sitter AST parsing to provide structural code navigation through three MCP tools: `smart_search`, `smart_outline`, and `smart_unfold`. This report documents a rigorous A/B comparison against the standard Explore agent (which uses Glob, Grep, and Read tools) to quantify the token savings and quality trade-offs.
+
+## Executive Summary
+
+| Metric | Smart Explore | Explore Agent | Advantage |
+|--------|:---:|:---:|---|
+| Discovery (cross-file search) | ~14,200 tokens | ~252,500 tokens | **17.8x cheaper** |
+| Targeted reads (specific symbols) | ~5,650 tokens | ~109,400 tokens | **19.4x cheaper** |
+| End-to-end (search + read) | ~4,200 tokens | ~45,000 tokens | **10-12x cheaper** |
+| Completeness | 5/5 full source returned | 4/5 (truncated longest method) | Smart Explore more reliable |
+| Speed | Under 2s per call | 5-66s per call | **10-30x faster** |
+
+## Methodology
+
+### Test Environment
+
+- **Codebase**: claude-mem (`src/` directory, 194 TypeScript files, 1,206 parsed symbols)
+- **Model**: Claude Opus 4.6 for both approaches
+- **Measurement**: Token counts from tool response metadata (`total_tokens` for Explore agents, self-reported `~N tokens for folded view` for Smart Explore)
+
+### Controls
+
+The Explore agents were explicitly instructed: *"Do NOT use smart_search, smart_outline, or smart_unfold tools. Only use Glob, Grep, and Read tools."* This was verified necessary after an initial round where agents opportunistically used the Smart Explore tools, invalidating the comparison.
+
+### Queries
+
+Five queries were selected to represent common exploration tasks:
+
+1. **"session processing"** -- Cross-cutting feature spanning multiple services
+2. **"shutdown"** -- Infrastructure concern touching 6+ files
+3. **"hook registration"** -- Architecture question about plugin system
+4. **"sqlite database"** -- Technology-specific search across the data layer
+5. **"worker-service.ts outline"** -- Single large file (1,225 lines) structural understanding
+
+## Round 1: Discovery
+
+*"What exists and where is it?"* -- Finding relevant files and symbols across the codebase.
+
+### Results
+
+| Query | Smart Explore | Explore Agent | Ratio | Explore Tool Calls |
+|-------|:---:|:---:|:---:|:---:|
+| session processing | ~4,391 t | 51,659 t | **11.8x** | 15 |
+| shutdown | ~3,852 t | 51,523 t | **13.4x** | 18 |
+| hook registration | ~1,930 t | 51,688 t | **26.8x** | 37 |
+| sqlite database | ~2,543 t | 58,633 t | **23.1x** | 16 |
+| worker-service outline | ~1,500 t | 38,973 t | **26.0x** | 15 |
+| **Total** | **~14,216 t** | **252,476 t** | **17.8x** | **101** |
+
+### What Each Returned
+
+**Smart Explore** (1 tool call each): 10 ranked symbols with signatures, line numbers, and JSDoc summaries, plus folded structural views of all matching files showing every function/class/interface with bodies collapsed.
+
+**Explore Agent** (15-37 tool calls each): Synthesized narrative reports with architecture diagrams, design pattern analysis, data flow explanations, complete interface dumps, and file structure maps. Significantly more explanatory prose.
+
+### Analysis
+
+The token gap is widest for narrowly-scoped queries ("hook registration" at 26.8x) because the Explore agent reads multiple full files to find relatively few relevant symbols. For broad queries ("session processing" at 11.8x), more of the file content is relevant, narrowing the ratio.
+
+Smart Explore's consistent 1-tool-call pattern means its cost is predictable. The Explore agent's cost varies with how many files it reads and how much it synthesizes -- ranging from 15 to 37 tool calls for comparable scope.
+
+## Round 2: Targeted Reads
+
+*"Show me this specific function."* -- Reading the implementation of a known symbol after discovery.
+
+Based on the Round 1 results, five specific symbols were selected as natural drill-down targets:
+
+| Target Symbol | File | Lines |
+|---------------|------|:---:|
+| `SessionManager.initializeSession` | services/worker/SessionManager.ts | 135 |
+| `performGracefulShutdown` | services/infrastructure/GracefulShutdown.ts | 48 |
+| `hookCommand` | cli/hook-command.ts | 45 |
+| `DatabaseManager.initialize` | services/sqlite/Database.ts | 27 |
+| `WorkerService.startSessionProcessor` | services/worker-service.ts | 158 |
+
+### Results
+
+| Symbol | Smart Unfold | Explore Agent | Ratio | Completeness |
+|--------|:---:|:---:|:---:|---|
+| initializeSession (135 lines) | ~1,800 t | 27,816 t | **15.5x** | Both returned full source |
+| performGracefulShutdown (48 lines) | ~700 t | 19,621 t | **28.0x** | Both returned full source |
+| hookCommand (45 lines) | ~650 t | 18,680 t | **28.7x** | Both returned full source |
+| DatabaseManager.initialize (27 lines) | ~400 t | 22,334 t | **55.8x** | Both returned full source |
+| startSessionProcessor (158 lines) | ~2,100 t | 20,906 t | **10.0x** | Smart Unfold: complete. Explore: **truncated** |
+| **Total** | **~5,650 t** | **109,357 t** | **19.4x** | |
+
+### Analysis
+
+**The ratio scales inversely with symbol size.** The smallest function (`initialize`, 27 lines) shows the biggest gap at 55.8x because the Explore agent still reads the entire 235-line file to extract 27 lines. The largest method (`startSessionProcessor`, 158 lines) narrows to 10x since more of the file is "useful."
+
+**Smart Unfold returned more complete code.** For the longest method (158 lines), the Explore agent truncated the error handling section with "... error handling continues ...", while `smart_unfold` returned the complete implementation. This is because smart_unfold extracts by AST node boundaries, guaranteeing completeness regardless of symbol size.
+
+**Explore agents add zero unique information for targeted reads.** When you already know the file path and symbol name, the agent's overhead is pure waste -- it reads the file, locates the function, and echoes it back. The only addition is a brief explanatory paragraph.
+
+## Combined Workflow
+
+The realistic workflow is discovery followed by targeted reading. Here is the end-to-end cost comparison for understanding a single function:
+
+### Smart Explore: search + unfold
+
+```
+smart_search("shutdown", path="./src")     ~3,852 tokens
+smart_unfold("GracefulShutdown.ts", "performGracefulShutdown")  ~700 tokens
+────────────────────────────────────────────────────────────────
+Total: ~4,552 tokens (2 tool calls, under 3 seconds)
+```
+
+### Explore Agent: single query
+
+```
+"Find and explain the shutdown logic"      ~51,523 tokens
+────────────────────────────────────────────────────────────────
+Total: ~51,523 tokens (18 tool calls, ~43 seconds)
+```
+
+**End-to-end ratio: 11.3x** -- and the Smart Explore workflow gives you the actual source code, while the Explore agent gives you a prose summary that may paraphrase or truncate.
+
+## Quality Assessment
+
+Neither approach is universally better. They optimize for different outcomes.
+
+### Smart Explore Strengths
+
+- **Predictable cost**: 1 tool call per operation, consistent token ranges
+- **Complete source code**: AST-based extraction guarantees full symbol bodies
+- **Structural context**: Folded views show every symbol in matching files
+- **Speed**: Sub-second responses enable rapid iteration
+- **Composability**: Search, outline, and unfold chain naturally
+
+### Explore Agent Strengths
+
+- **Synthesized understanding**: Produces architecture narratives, data flow diagrams, and design pattern analysis
+- **Cross-cutting explanation**: Connects concepts across files that individual symbol reads cannot
+- **Onboarding quality**: Output reads like documentation, not raw code
+- **Error handling insight**: Identifies edge cases and design decisions that require reading multiple related functions
+- **No prior knowledge needed**: Can answer open-ended questions without knowing file paths or symbol names
+
+### Quality by Task Type
+
+| Task | Better Tool | Why |
+|------|-------------|-----|
+| "Where is X defined?" | Smart Explore | One call, exact answer |
+| "What functions are in this file?" | Smart Explore | Outline returns complete structural map |
+| "Show me this function" | Smart Explore | Unfold returns exact source, never truncates |
+| "How does feature X work end-to-end?" | Explore Agent | Reads multiple files and synthesizes narrative |
+| "What design patterns are used here?" | Explore Agent | Requires reading and interpreting, not just extracting |
+| "Help me understand this codebase" | Explore Agent | Produces onboarding-quality documentation |
+
+## When to Use Which
+
+**Use Smart Explore when:**
+- You know what you are looking for (function name, concept, file)
+- You need source code, not explanation
+- You are iterating quickly (read, modify, read again)
+- Token budget matters (large codebases, long sessions)
+- You need file structure at a glance
+
+**Use the Explore Agent when:**
+- You need synthesized cross-cutting understanding
+- The question is open-ended ("how does this system work?")
+- You are writing documentation or architecture reviews
+- You need to understand *why*, not just *what*
+- You are onboarding to an unfamiliar codebase
+
+**Use both when:**
+- Start with Smart Explore for discovery and navigation
+- Escalate to Explore Agent only for deep analysis that requires multi-file synthesis
+- This hybrid approach captures most of the token savings while preserving access to deep understanding when needed
+
+## Token Economics Reference
+
+| Operation | Tokens | Use Case |
+|-----------|:---:|----------|
+| `smart_search` | 2,000-6,000 | Cross-file symbol discovery |
+| `smart_outline` | 1,000-2,000 | Single file structural map |
+| `smart_unfold` | 400-2,100 | Single symbol full source |
+| `smart_search` + `smart_unfold` | 3,000-8,000 | End-to-end: find and read |
+| Explore Agent (targeted) | 18,000-28,000 | Single function with explanation |
+| Explore Agent (cross-cutting) | 39,000-59,000 | Architecture-level understanding |
+| Read (full file) | 8,000-15,000+ | Complete file contents |
+
+### Savings by Workflow
+
+| Workflow | Smart Explore | Traditional | Savings |
+|----------|:---:|:---:|:---:|
+| Understand one file | outline + unfold (~3,100 t) | Read full file (~12,000 t) | **4x** |
+| Find a function across codebase | search (~3,500 t) | Explore agent (~50,000 t) | **14x** |
+| Find and read a specific function | search + unfold (~4,500 t) | Explore agent (~50,000 t) | **11x** |
+| Navigate a 1,200-line file | outline (~1,500 t) | Read full file (~12,000 t) | **8x** |

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://raw.githubusercontent.com/thedotmack/claude-mem/main/installer/dist/index.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 ""

install/public/installer.js

@@ -0,0 +1,17 @@
+#!/usr/bin/env node
+
+// claude-mem installer redirect
+// The old bundled installer has been replaced by npx claude-mem.
+// This script now redirects users to the new install method.
+
+console.log('');
+console.log('\x1b[33mThe bundled installer has been replaced.\x1b[0m');
+console.log('');
+console.log('\x1b[32mInstall claude-mem with:\x1b[0m');
+console.log('');
+console.log('  \x1b[36mnpx claude-mem install\x1b[0m');
+console.log('');
+console.log('For more info, visit: \x1b[36mhttps://docs.claude-mem.ai/installation\x1b[0m');
+console.log('');
+
+process.exit(0);

install/vercel.json

@@ -1,5 +1,8 @@
 {
   "$schema": "https://openapi.vercel.sh/vercel.json",
+  "rewrites": [
+    { "source": "/", "destination": "/install.sh" }
+  ],
   "headers": [
     {
       "source": "/(.*)\\.sh",

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/

openclaw/SKILL.md

@@ -1,6 +1,6 @@
 # Claude-Mem OpenClaw Plugin — Setup Guide
 
-This guide walks through setting up the claude-mem plugin on an OpenClaw gateway. By the end, your agents will have persistent memory across sessions, a live-updating MEMORY.md in their workspace, and optionally a real-time observation feed streaming to a messaging channel.
+This guide walks through setting up the claude-mem plugin on an OpenClaw gateway. By the end, your agents will have persistent memory across sessions via system prompt context injection, and optionally a real-time observation feed streaming to a messaging channel.
 
 ## Quick Install (Recommended)
 
@@ -138,7 +138,9 @@ Add the `claude-mem` plugin to your OpenClaw gateway configuration:
 
 - **`project`** (string, default: `"openclaw"`) — The project name that scopes all observations in the memory database. Use a unique name per gateway/use-case so observations don't mix. For example, if this gateway runs a coding bot, use `"coding-bot"`.
 
-- **`syncMemoryFile`** (boolean, default: `true`) — When enabled, the plugin writes a `MEMORY.md` file to each agent's workspace directory. This file contains the full timeline of observations and summaries from previous sessions, and it updates on every tool use so agents always have fresh context. Set to `false` only if you don't want the plugin writing files to agent workspaces.
+- **`syncMemoryFile`** (boolean, default: `true`) — When enabled, the plugin injects the observation timeline into each agent's system prompt via the `before_prompt_build` hook. This gives agents cross-session context without writing to MEMORY.md. Set to `false` to disable context injection entirely (observations are still recorded).
+
+- **`syncMemoryFileExclude`** (string[], default: `[]`) — Agent IDs excluded from automatic context injection. Useful for agents that curate their own memory. Observations are still recorded for excluded agents.
 
 - **`workerPort`** (number, default: `37777`) — The port where the claude-mem worker service is listening. Only change this if you configured the worker to use a different port.
 
@@ -168,13 +170,14 @@ The observation feed shows `disconnected` because we haven't configured it yet.
 
 Have an agent do some work. The plugin automatically records observations through these OpenClaw events:
 
-1. **`before_agent_start`** — Initializes a claude-mem session when the agent starts, syncs MEMORY.md to the workspace
-2. **`tool_result_persist`** — Records each tool use (Read, Write, Bash, etc.) as an observation, re-syncs MEMORY.md
-3. **`agent_end`** — Summarizes the session and marks it complete
+1. **`before_agent_start`** — Initializes a claude-mem session when the agent starts
+2. **`before_prompt_build`** — Injects the observation timeline into the agent's system prompt (cached for 60s)
+3. **`tool_result_persist`** — Records each tool use (Read, Write, Bash, etc.) as an observation
+4. **`agent_end`** — Summarizes the session and marks it complete
 
 All of this happens automatically. No additional configuration needed.
 
-To verify it's working, check the agent's workspace directory for a `MEMORY.md` file after the agent runs. It should contain a formatted timeline of observations.
+To verify it's working, check the worker's viewer UI at http://localhost:37777 to see observations appearing after the agent runs.
 
 You can also check the worker's viewer UI at http://localhost:37777 to see observations appearing in real time.
 
@@ -372,10 +375,11 @@ Shows observation feed status. Accepts optional `on`/`off` argument.
 ```
 OpenClaw Gateway
   │
-  ├── before_agent_start ──→ Sync MEMORY.md + Init session
-  ├── tool_result_persist ──→ Record observation + Re-sync MEMORY.md
+  ├── before_agent_start ───→ Init session
+  ├── before_prompt_build ──→ Inject context into system prompt
+  ├── tool_result_persist ──→ Record observation
   ├── agent_end ────────────→ Summarize + Complete session
-  └── gateway_start ────────→ Reset session tracking
+  └── gateway_start ────────→ Reset session tracking + context cache
                     │
                     ▼
          Claude-Mem Worker (localhost:37777)
@@ -383,17 +387,15 @@ OpenClaw Gateway
            ├── POST /api/sessions/observations
            ├── POST /api/sessions/summarize
            ├── POST /api/sessions/complete
-           ├── GET  /api/context/inject ──→ MEMORY.md content
+           ├── GET  /api/context/inject ──→ System prompt context
            └── GET  /stream ─────────────→ SSE → Messaging channels
 ```
 
-### MEMORY.md live sync
+### System prompt context injection
 
-The plugin writes `MEMORY.md` to each agent's workspace with the full observation timeline. It updates:
-- On every `before_agent_start` — agent gets fresh context before starting
-- On every `tool_result_persist` — context stays current as the agent works
+The plugin injects the observation timeline into each agent's system prompt via the `before_prompt_build` hook. The content comes from the worker's `GET /api/context/inject` endpoint. Context is cached for 60 seconds per project to avoid re-fetching on every LLM turn. The cache is cleared on gateway restart.
 
-Updates are fire-and-forget (non-blocking). The agent is never held up waiting for MEMORY.md to write.
+This keeps MEMORY.md under the agent's control for curated long-term memory, while the observation timeline is delivered through the system prompt.
 
 ### Observation recording
 
@@ -401,10 +403,11 @@ Every tool use (Read, Write, Bash, etc.) is sent to the claude-mem worker as an
 
 ### Session lifecycle
 
-- **`before_agent_start`** — Creates a session in the worker, syncs MEMORY.md. Short prompts (under 10 chars) skip session init but still sync.
-- **`tool_result_persist`** — Records observation (fire-and-forget), re-syncs MEMORY.md (fire-and-forget). Tool responses are truncated to 1000 characters.
+- **`before_agent_start`** — Creates a session in the worker.
+- **`before_prompt_build`** — Fetches the observation timeline and returns it as `appendSystemContext`. Cached for 60s.
+- **`tool_result_persist`** — Records observation (fire-and-forget). Tool responses are truncated to 1000 characters.
 - **`agent_end`** — Sends the last assistant message for summarization, then completes the session. Both fire-and-forget.
-- **`gateway_start`** — Clears all session tracking (session IDs, workspace mappings) so agents start fresh.
+- **`gateway_start`** — Clears all session tracking (session IDs, context cache) so agents start fresh.
 
 ### Observation feed
 
@@ -417,7 +420,7 @@ A background service connects to the worker's SSE stream and forwards `new_obser
 | Worker health check fails | Is bun installed? (`bun --version`). Is something else on port 37777? (`lsof -i :37777`). Try running directly: `bun plugin/scripts/worker-service.cjs start` |
 | Worker started from Claude Code install but not responding | Check `cd ~/.claude/plugins/marketplaces/thedotmack && npm run worker:status`. May need `npm run worker:restart`. |
 | Worker started from cloned repo but not responding | Check `cd /path/to/claude-mem && npm run worker:status`. Make sure you ran `npm install && npm run build` first. |
-| No MEMORY.md appearing | Check that `syncMemoryFile` is not set to `false`. Verify the agent's event context includes `workspaceDir`. |
+| No context in agent system prompt | Check that `syncMemoryFile` is not set to `false`. Check that the agent's ID is not in `syncMemoryFileExclude`. Verify the worker is running and has observations. |
 | Observations not being recorded | Check gateway logs for `[claude-mem]` messages. The worker must be running and reachable on localhost:37777. |
 | Feed shows `disconnected` | Worker's `/stream` endpoint not reachable. Check `workerPort` matches the actual worker port. |
 | Feed shows `reconnecting` | Connection dropped. The plugin auto-reconnects — wait up to 30 seconds. |
@@ -451,7 +454,8 @@ A background service connects to the worker's SSE stream and forwards `new_obser
 | Field | Type | Default | Description |
 |-------|------|---------|-------------|
 | `project` | string | `"openclaw"` | Project name scoping observations in the database |
-| `syncMemoryFile` | boolean | `true` | Write MEMORY.md to agent workspaces |
+| `syncMemoryFile` | boolean | `true` | Inject observation context into agent system prompt |
+| `syncMemoryFileExclude` | string[] | `[]` | Agent IDs excluded from context injection |
 | `workerPort` | number | `37777` | Claude-mem worker service port |
 | `observationFeed.enabled` | boolean | `false` | Stream observations to a messaging channel |
 | `observationFeed.channel` | string | — | Channel type: `telegram`, `discord`, `slack`, `signal`, `whatsapp`, `line` |

openclaw/openclaw.plugin.json

@@ -3,10 +3,10 @@
   "name": "Claude-Mem (Persistent Memory)",
   "description": "Official OpenClaw plugin for Claude-Mem. Records observations from embedded runner sessions and streams them to messaging channels.",
   "kind": "memory",
-  "version": "1.0.0",
+  "version": "10.4.1",
   "author": "thedotmack",
   "homepage": "https://claude-mem.com",
-  "skills": ["skills/make-plan", "skills/do-plan"],
+  "skills": ["skills/make-plan", "skills/do"],
   "configSchema": {
     "type": "object",
     "additionalProperties": false,
@@ -14,7 +14,13 @@
       "syncMemoryFile": {
         "type": "boolean",
         "default": true,
-        "description": "Automatically sync MEMORY.md on session start"
+        "description": "Inject observation context into the agent system prompt via before_prompt_build hook. When true, agents receive cross-session context without MEMORY.md being overwritten."
+      },
+      "syncMemoryFileExclude": {
+        "type": "array",
+        "items": { "type": "string" },
+        "default": [],
+        "description": "Agent IDs excluded from automatic context injection (observations are still recorded, only prompt injection is skipped)"
       },
       "workerPort": {
         "type": "number",

openclaw/skills/do/SKILL.md

@@ -0,0 +1 @@
+../../../plugin/skills/do/SKILL.md

openclaw/skills/make-plan/SKILL.md

@@ -1,63 +0,0 @@
----
-name: make-plan
-description: Create a detailed, phased implementation plan with documentation discovery. Use when asked to plan a feature, task, or multi-step implementation — especially before executing with do-plan.
----
-
-# Make Plan
-
-You are an ORCHESTRATOR. Create an LLM-friendly plan in phases that can be executed consecutively in new chat contexts.
-
-## Delegation Model
-
-Use subagents for *fact gathering and extraction* (docs, examples, signatures, grep results). Keep *synthesis and plan authoring* with the orchestrator (phase boundaries, task framing, final wording). If a subagent report is incomplete or lacks evidence, re-check with targeted reads/greps before finalizing.
-
-### Subagent Reporting Contract (MANDATORY)
-
-Each subagent response must include:
-1. Sources consulted (files/URLs) and what was read
-2. Concrete findings (exact API names/signatures; exact file paths/locations)
-3. Copy-ready snippet locations (example files/sections to copy)
-4. "Confidence" note + known gaps (what might still be missing)
-
-Reject and redeploy the subagent if it reports conclusions without sources.
-
-## Plan Structure
-
-### Phase 0: Documentation Discovery (ALWAYS FIRST)
-
-Before planning implementation, deploy "Documentation Discovery" subagents to:
-1. Search for and read relevant documentation, examples, and existing patterns
-2. Identify the actual APIs, methods, and signatures available (not assumed)
-3. Create a brief "Allowed APIs" list citing specific documentation sources
-4. Note any anti-patterns to avoid (methods that DON'T exist, deprecated parameters)
-
-The orchestrator consolidates findings into a single Phase 0 output.
-
-### Each Implementation Phase Must Include
-
-1. **What to implement** — Frame tasks to COPY from docs, not transform existing code
-   - Good: "Copy the V2 session pattern from docs/examples.ts:45-60"
-   - Bad: "Migrate the existing code to V2"
-2. **Documentation references** — Cite specific files/lines for patterns to follow
-3. **Verification checklist** — How to prove this phase worked (tests, grep checks)
-4. **Anti-pattern guards** — What NOT to do (invented APIs, undocumented params)
-
-### Final Phase: Verification
-
-1. Verify all implementations match documentation
-2. Check for anti-patterns (grep for known bad patterns)
-3. Run tests to confirm functionality
-
-## Key Principles
-
-- Documentation Availability ≠ Usage: Explicitly require reading docs
-- Task Framing Matters: Direct agents to docs, not just outcomes
-- Verify > Assume: Require proof, not assumptions about APIs
-- Session Boundaries: Each phase should be self-contained with its own doc references
-
-## Anti-Patterns to Prevent
-
-- Inventing API methods that "should" exist
-- Adding parameters not in documentation
-- Skipping verification steps
-- Assuming structure without checking examples

openclaw/skills/make-plan/SKILL.md

@@ -0,0 +1 @@
+../../../plugin/skills/make-plan/SKILL.md

openclaw/src/index.test.ts

@@ -87,9 +87,11 @@ function createMockApi(pluginConfigOverride: Record<string, any> = {}) {
     getEventHandlers: (event: string) => eventHandlers.get(event) || [],
     fireEvent: async (event: string, data: any, ctx: any = {}) => {
       const handlers = eventHandlers.get(event) || [];
+      let lastResult: any;
       for (const handler of handlers) {
-        await handler(data, ctx);
+        lastResult = await handler(data, ctx);
       }
+      return lastResult;
     },
   };
 }
@@ -106,6 +108,7 @@ describe("claudeMemPlugin", () => {
     assert.ok(getEventHandlers("session_start").length > 0, "session_start handler registered");
     assert.ok(getEventHandlers("after_compaction").length > 0, "after_compaction handler registered");
     assert.ok(getEventHandlers("before_agent_start").length > 0, "before_agent_start handler registered");
+    assert.ok(getEventHandlers("before_prompt_build").length > 0, "before_prompt_build handler registered");
     assert.ok(getEventHandlers("tool_result_persist").length > 0, "tool_result_persist handler registered");
     assert.ok(getEventHandlers("agent_end").length > 0, "agent_end handler registered");
     assert.ok(getEventHandlers("gateway_start").length > 0, "gateway_start handler registered");
@@ -535,11 +538,10 @@ describe("Observation I/O event handlers", () => {
   });
 });
 
-describe("MEMORY.md context sync", () => {
+describe("before_prompt_build context injection", () => {
   let workerServer: Server;
   let workerPort: number;
   let receivedRequests: Array<{ method: string; url: string; body: any }> = [];
-  let tmpDir: string;
   let contextResponse = "# Claude-Mem Context\n\n## Timeline\n- Session 1: Did some work";
 
   function startWorkerMock(): Promise<number> {
@@ -586,21 +588,20 @@ describe("MEMORY.md context sync", () => {
     receivedRequests = [];
     contextResponse = "# Claude-Mem Context\n\n## Timeline\n- Session 1: Did some work";
     workerPort = await startWorkerMock();
-    tmpDir = await mkdtemp(join(tmpdir(), "claude-mem-test-"));
   });
 
   afterEach(async () => {
     workerServer?.close();
-    await rm(tmpDir, { recursive: true, force: true });
   });
 
-  it("writes MEMORY.md to workspace on before_agent_start", async () => {
+  it("returns appendSystemContext from before_prompt_build", async () => {
     const { api, logs, fireEvent } = createMockApi({ workerPort });
     claudeMemPlugin(api);
 
-    await fireEvent("before_agent_start", {
+    const result = await fireEvent("before_prompt_build", {
       prompt: "Help me write a function",
-    }, { sessionKey: "sync-test", workspaceDir: tmpDir });
+      messages: [],
+    }, { agentId: "main" });
 
     await new Promise((resolve) => setTimeout(resolve, 200));
 
@@ -608,142 +609,143 @@ describe("MEMORY.md context sync", () => {
     assert.ok(contextRequest, "should request context from worker");
     assert.ok(contextRequest!.url!.includes("projects=openclaw"));
 
-    const memoryContent = await readFile(join(tmpDir, "MEMORY.md"), "utf-8");
-    assert.ok(memoryContent.includes("Claude-Mem Context"), "MEMORY.md should contain context");
-    assert.ok(memoryContent.includes("Session 1"), "MEMORY.md should contain timeline");
-    assert.ok(logs.some((l) => l.includes("MEMORY.md synced")));
+    assert.ok(result, "should return a result");
+    assert.ok(result.appendSystemContext, "should return appendSystemContext");
+    assert.ok(result.appendSystemContext.includes("Claude-Mem Context"), "should contain context");
+    assert.ok(result.appendSystemContext.includes("Session 1"), "should contain timeline");
+    assert.ok(logs.some((l) => l.includes("Context injected via system prompt")));
   });
 
-  it("syncs MEMORY.md on every before_agent_start call", async () => {
-    const { api, fireEvent } = createMockApi({ workerPort });
-    claudeMemPlugin(api);
+  it("does not write MEMORY.md on before_agent_start", async () => {
+    const tmpDir = await mkdtemp(join(tmpdir(), "claude-mem-test-"));
+    try {
+      const { api, fireEvent } = createMockApi({ workerPort });
+      claudeMemPlugin(api);
 
-    await fireEvent("before_agent_start", {
-      prompt: "First prompt for this agent",
-    }, { sessionKey: "agent-a", workspaceDir: tmpDir });
+      await fireEvent("before_agent_start", {
+        prompt: "Help me write a function",
+      }, { sessionKey: "sync-test", workspaceDir: tmpDir });
 
-    await new Promise((resolve) => setTimeout(resolve, 200));
+      await new Promise((resolve) => setTimeout(resolve, 200));
 
-    const firstContextRequests = receivedRequests.filter((r) => r.url?.startsWith("/api/context/inject"));
-    assert.equal(firstContextRequests.length, 1, "first call should fetch context");
-
-    await fireEvent("before_agent_start", {
-      prompt: "Second prompt for same agent",
-    }, { sessionKey: "agent-a", workspaceDir: tmpDir });
-
-    await new Promise((resolve) => setTimeout(resolve, 200));
-
-    const allContextRequests = receivedRequests.filter((r) => r.url?.startsWith("/api/context/inject"));
-    assert.equal(allContextRequests.length, 2, "should re-fetch context on every call");
+      let memoryExists = true;
+      try {
+        await readFile(join(tmpDir, "MEMORY.md"), "utf-8");
+      } catch {
+        memoryExists = false;
+      }
+      assert.ok(!memoryExists, "MEMORY.md should not be created by before_agent_start");
+    } finally {
+      await rm(tmpDir, { recursive: true, force: true });
+    }
   });
 
-  it("syncs MEMORY.md on tool_result_persist via fire-and-forget", async () => {
-    const { api, fireEvent } = createMockApi({ workerPort });
-    claudeMemPlugin(api);
+  it("does not sync MEMORY.md on tool_result_persist", async () => {
+    const tmpDir = await mkdtemp(join(tmpdir(), "claude-mem-test-"));
+    try {
+      const { api, fireEvent } = createMockApi({ workerPort });
+      claudeMemPlugin(api);
 
-    // Init session to register workspace dir
-    await fireEvent("before_agent_start", {
-      prompt: "Help me write a function",
-    }, { sessionKey: "tool-sync", workspaceDir: tmpDir });
+      await fireEvent("before_agent_start", {
+        prompt: "Help me write a function",
+      }, { sessionKey: "tool-sync", workspaceDir: tmpDir });
 
-    await new Promise((resolve) => setTimeout(resolve, 200));
+      await new Promise((resolve) => setTimeout(resolve, 200));
 
-    const preToolContextRequests = receivedRequests.filter((r) => r.url?.startsWith("/api/context/inject"));
-    assert.equal(preToolContextRequests.length, 1, "before_agent_start should sync once");
+      await fireEvent("tool_result_persist", {
+        toolName: "Read",
+        params: { file_path: "/src/app.ts" },
+        message: { content: [{ type: "text", text: "file contents" }] },
+      }, { sessionKey: "tool-sync" });
 
-    // Fire tool result — should trigger another MEMORY.md sync
-    await fireEvent("tool_result_persist", {
-      toolName: "Read",
-      params: { file_path: "/src/app.ts" },
-      message: { content: [{ type: "text", text: "file contents" }] },
-    }, { sessionKey: "tool-sync" });
+      await new Promise((resolve) => setTimeout(resolve, 200));
 
-    await new Promise((resolve) => setTimeout(resolve, 200));
+      const contextRequests = receivedRequests.filter((r) => r.url?.startsWith("/api/context/inject"));
+      assert.equal(contextRequests.length, 0, "tool_result_persist should not fetch context");
 
-    const postToolContextRequests = receivedRequests.filter((r) => r.url?.startsWith("/api/context/inject"));
-    assert.equal(postToolContextRequests.length, 2, "tool_result_persist should trigger another sync");
-
-    const memoryContent = await readFile(join(tmpDir, "MEMORY.md"), "utf-8");
-    assert.ok(memoryContent.includes("Claude-Mem Context"), "MEMORY.md should be updated");
+      let memoryExists = true;
+      try {
+        await readFile(join(tmpDir, "MEMORY.md"), "utf-8");
+      } catch {
+        memoryExists = false;
+      }
+      assert.ok(!memoryExists, "MEMORY.md should not be written by tool_result_persist");
+    } finally {
+      await rm(tmpDir, { recursive: true, force: true });
+    }
   });
 
-  it("skips MEMORY.md sync when syncMemoryFile is false", async () => {
+  it("skips context injection when syncMemoryFile is false", async () => {
     const { api, fireEvent } = createMockApi({ workerPort, syncMemoryFile: false });
     claudeMemPlugin(api);
 
-    await fireEvent("before_agent_start", {
+    const result = await fireEvent("before_prompt_build", {
       prompt: "Help me write a function",
-    }, { sessionKey: "no-sync", workspaceDir: tmpDir });
+      messages: [],
+    }, { agentId: "main" });
 
     await new Promise((resolve) => setTimeout(resolve, 200));
 
     const contextRequest = receivedRequests.find((r) => r.url?.startsWith("/api/context/inject"));
-    assert.ok(!contextRequest, "should not fetch context when sync disabled");
+    assert.ok(!contextRequest, "should not fetch context when injection disabled");
+    assert.equal(result, undefined, "should return undefined when injection disabled");
   });
 
-  it("skips MEMORY.md sync when no workspaceDir in context", async () => {
-    const { api, fireEvent } = createMockApi({ workerPort });
+  it("skips context injection for excluded agents", async () => {
+    const { api, fireEvent } = createMockApi({ workerPort, syncMemoryFileExclude: ["snarf"] });
     claudeMemPlugin(api);
 
-    await fireEvent("before_agent_start", {
-      prompt: "Help me write a function",
-    }, { sessionKey: "no-workspace" });
+    const result = await fireEvent("before_prompt_build", {
+      prompt: "Help me",
+      messages: [],
+    }, { agentId: "snarf" });
 
     await new Promise((resolve) => setTimeout(resolve, 200));
 
     const contextRequest = receivedRequests.find((r) => r.url?.startsWith("/api/context/inject"));
-    assert.ok(!contextRequest, "should not fetch context without workspaceDir");
+    assert.ok(!contextRequest, "should not fetch context for excluded agent");
+    assert.equal(result, undefined, "should return undefined for excluded agent");
   });
 
-  it("skips writing MEMORY.md when context is empty", async () => {
+  it("injects context for non-excluded agents", async () => {
+    const { api, fireEvent } = createMockApi({ workerPort, syncMemoryFileExclude: ["snarf"] });
+    claudeMemPlugin(api);
+
+    const result = await fireEvent("before_prompt_build", {
+      prompt: "Help me",
+      messages: [],
+    }, { agentId: "main" });
+
+    await new Promise((resolve) => setTimeout(resolve, 200));
+
+    assert.ok(result, "should return a result for non-excluded agent");
+    assert.ok(result.appendSystemContext, "should inject context for non-excluded agent");
+  });
+
+  it("returns undefined when context is empty", async () => {
     contextResponse = "   ";
     const { api, logs, fireEvent } = createMockApi({ workerPort });
     claudeMemPlugin(api);
 
-    await fireEvent("before_agent_start", {
+    const result = await fireEvent("before_prompt_build", {
       prompt: "Help me write a function",
-    }, { sessionKey: "empty-ctx", workspaceDir: tmpDir });
+      messages: [],
+    }, { agentId: "main" });
 
     await new Promise((resolve) => setTimeout(resolve, 200));
 
-    assert.ok(!logs.some((l) => l.includes("MEMORY.md synced")), "should not log sync for empty context");
-  });
-
-  it("gateway_start resets sync tracking so next agent re-syncs", async () => {
-    const { api, fireEvent } = createMockApi({ workerPort });
-    claudeMemPlugin(api);
-
-    // First sync
-    await fireEvent("before_agent_start", {
-      prompt: "Help me write a function",
-    }, { sessionKey: "agent-1", workspaceDir: tmpDir });
-
-    await new Promise((resolve) => setTimeout(resolve, 200));
-
-    const firstContextRequests = receivedRequests.filter((r) => r.url?.startsWith("/api/context/inject"));
-    assert.equal(firstContextRequests.length, 1);
-
-    // Gateway restart
-    await fireEvent("gateway_start", {}, {});
-
-    // Second sync after gateway restart — same workspace should re-sync
-    await fireEvent("before_agent_start", {
-      prompt: "Help me after gateway restart",
-    }, { sessionKey: "agent-1", workspaceDir: tmpDir });
-
-    await new Promise((resolve) => setTimeout(resolve, 200));
-
-    const allContextRequests = receivedRequests.filter((r) => r.url?.startsWith("/api/context/inject"));
-    assert.equal(allContextRequests.length, 2, "should re-fetch context after gateway restart");
+    assert.equal(result, undefined, "should return undefined for empty context");
+    assert.ok(!logs.some((l) => l.includes("Context injected")), "should not log injection for empty context");
   });
 
   it("uses custom project name in context inject URL", async () => {
     const { api, fireEvent } = createMockApi({ workerPort, project: "my-bot" });
     claudeMemPlugin(api);
 
-    await fireEvent("before_agent_start", {
+    await fireEvent("before_prompt_build", {
       prompt: "Help me write a function",
-    }, { sessionKey: "proj-test", workspaceDir: tmpDir });
+      messages: [],
+    }, { agentId: "main" });
 
     await new Promise((resolve) => setTimeout(resolve, 200));
 
@@ -751,6 +753,23 @@ describe("MEMORY.md context sync", () => {
     assert.ok(contextRequest, "should request context");
     assert.ok(contextRequest!.url!.includes("projects=my-bot"), "should use custom project name");
   });
+
+  it("includes agent-scoped project in context request", async () => {
+    const { api, fireEvent } = createMockApi({ workerPort });
+    claudeMemPlugin(api);
+
+    await fireEvent("before_prompt_build", {
+      prompt: "Help me",
+      messages: [],
+    }, { agentId: "debugger" });
+
+    await new Promise((resolve) => setTimeout(resolve, 200));
+
+    const contextRequest = receivedRequests.find((r) => r.url?.startsWith("/api/context/inject"));
+    assert.ok(contextRequest, "should request context");
+    const url = decodeURIComponent(contextRequest!.url!);
+    assert.ok(url.includes("openclaw,openclaw-debugger"), "should include both base and agent-scoped projects");
+  });
 });
 
 describe("SSE stream integration", () => {

openclaw/src/index.ts

@@ -1,5 +1,5 @@
-import { writeFile } from "fs/promises";
-import { join } from "path";
+// No file-system imports needed — context is injected via system prompt hook,
+// not by writing to MEMORY.md.
 
 // Minimal type declarations for the OpenClaw Plugin SDK.
 // These match the real OpenClawPluginApi provided by the gateway at runtime.
@@ -35,6 +35,18 @@ interface BeforeAgentStartEvent {
   prompt?: string;
 }
 
+interface BeforePromptBuildEvent {
+  prompt: string;
+  messages: unknown[];
+}
+
+interface BeforePromptBuildResult {
+  systemPrompt?: string;
+  prependContext?: string;
+  prependSystemContext?: string;
+  appendSystemContext?: string;
+}
+
 interface ToolResultPersistEvent {
   toolName?: string;
   params?: Record<string, unknown>;
@@ -87,6 +99,7 @@ interface MessageContext {
 }
 
 type EventCallback<T> = (event: T, ctx: EventContext) => void | Promise<void>;
+type PromptBuildCallback = (event: BeforePromptBuildEvent, ctx: EventContext) => BeforePromptBuildResult | Promise<BeforePromptBuildResult | void> | void;
 type MessageEventCallback<T> = (event: T, ctx: MessageContext) => void | Promise<void>;
 
 interface OpenClawPluginApi {
@@ -109,7 +122,8 @@ interface OpenClawPluginApi {
     requireAuth?: boolean;
     handler: (ctx: PluginCommandContext) => PluginCommandResult | Promise<PluginCommandResult>;
   }) => void;
-  on: ((event: "before_agent_start", callback: EventCallback<BeforeAgentStartEvent>) => void) &
+  on: ((event: "before_prompt_build", callback: PromptBuildCallback) => void) &
+      ((event: "before_agent_start", callback: EventCallback<BeforeAgentStartEvent>) => void) &
       ((event: "tool_result_persist", callback: EventCallback<ToolResultPersistEvent>) => void) &
       ((event: "agent_end", callback: EventCallback<AgentEndEvent>) => void) &
       ((event: "session_start", callback: EventCallback<SessionStartEvent>) => void) &
@@ -166,6 +180,7 @@ interface FeedEmojiConfig {
 
 interface ClaudeMemPluginConfig {
   syncMemoryFile?: boolean;
+  syncMemoryFileExclude?: string[];
   project?: string;
   workerPort?: number;
   observationFeed?: {
@@ -532,8 +547,8 @@ export default function claudeMemPlugin(api: OpenClawPluginApi): void {
   // Session tracking for observation I/O
   // ------------------------------------------------------------------
   const sessionIds = new Map<string, string>();
-  const workspaceDirsBySessionKey = new Map<string, string>();
   const syncMemoryFile = userConfig.syncMemoryFile !== false; // default true
+  const syncMemoryFileExclude = new Set(userConfig.syncMemoryFileExclude || []);
 
   function getContentSessionId(sessionKey?: string): string {
     const key = sessionKey || "default";
@@ -543,27 +558,45 @@ export default function claudeMemPlugin(api: OpenClawPluginApi): void {
     return sessionIds.get(key)!;
   }
 
-  async function syncMemoryToWorkspace(workspaceDir: string, ctx?: EventContext): Promise<void> {
+  function shouldInjectContext(ctx?: EventContext): boolean {
+    if (!syncMemoryFile) return false;
+    const agentId = ctx?.agentId;
+    if (agentId && syncMemoryFileExclude.has(agentId)) return false;
+    return true;
+  }
+
+  // TTL cache for context injection to avoid re-fetching on every LLM turn.
+  // before_prompt_build fires on every turn; caching for 60s keeps the worker
+  // load manageable while still picking up new observations reasonably quickly.
+  const CONTEXT_CACHE_TTL_MS = 60_000;
+  const contextCache = new Map<string, { text: string; fetchedAt: number }>();
+
+  async function getContextForPrompt(ctx?: EventContext): Promise<string | null> {
     // Include both the base project and agent-scoped project (e.g. "openclaw" + "openclaw-main")
     const projects = [baseProjectName];
     const agentProject = ctx ? getProjectName(ctx) : null;
     if (agentProject && agentProject !== baseProjectName) {
       projects.push(agentProject);
     }
+    const cacheKey = projects.join(",");
+
+    // Return cached context if still fresh
+    const cached = contextCache.get(cacheKey);
+    if (cached && Date.now() - cached.fetchedAt < CONTEXT_CACHE_TTL_MS) {
+      return cached.text;
+    }
+
     const contextText = await workerGetText(
       workerPort,
-      `/api/context/inject?projects=${encodeURIComponent(projects.join(","))}`,
+      `/api/context/inject?projects=${encodeURIComponent(cacheKey)}`,
       api.logger
     );
     if (contextText && contextText.trim().length > 0) {
-      try {
-        await writeFile(join(workspaceDir, "MEMORY.md"), contextText, "utf-8");
-        api.logger.info(`[claude-mem] MEMORY.md synced to ${workspaceDir}`);
-      } catch (writeError: unknown) {
-        const msg = writeError instanceof Error ? writeError.message : String(writeError);
-        api.logger.warn(`[claude-mem] Failed to write MEMORY.md: ${msg}`);
-      }
+      const trimmed = contextText.trim();
+      contextCache.set(cacheKey, { text: trimmed, fetchedAt: Date.now() });
+      return trimmed;
     }
+    return null;
   }
 
   // ------------------------------------------------------------------
@@ -611,14 +644,9 @@ export default function claudeMemPlugin(api: OpenClawPluginApi): void {
   });
 
   // ------------------------------------------------------------------
-  // Event: before_agent_start — init session + sync MEMORY.md + track workspace
+  // Event: before_agent_start — init session
   // ------------------------------------------------------------------
   api.on("before_agent_start", async (event, ctx) => {
-    // Track workspace dir so tool_result_persist can sync MEMORY.md later
-    if (ctx.workspaceDir) {
-      workspaceDirsBySessionKey.set(ctx.sessionKey || "default", ctx.workspaceDir);
-    }
-
     // Initialize session in the worker so observations are not skipped
     // (the privacy check requires a stored user prompt to exist)
     const contentSessionId = getContentSessionId(ctx.sessionKey);
@@ -627,21 +655,37 @@ export default function claudeMemPlugin(api: OpenClawPluginApi): void {
       project: getProjectName(ctx),
       prompt: event.prompt || "agent run",
     }, api.logger);
+  });
 
-    // Sync MEMORY.md before agent runs (provides context to agent)
-    if (syncMemoryFile && ctx.workspaceDir) {
-      await syncMemoryToWorkspace(ctx.workspaceDir, ctx);
+  // ------------------------------------------------------------------
+  // Event: before_prompt_build — inject context into system prompt
+  //
+  // Instead of writing to MEMORY.md (which conflicts with agent-curated
+  // memory), inject the observation timeline via appendSystemContext.
+  // This keeps MEMORY.md under the agent's control while still providing
+  // cross-session context to the LLM.
+  // ------------------------------------------------------------------
+  api.on("before_prompt_build", async (_event, ctx) => {
+    if (!shouldInjectContext(ctx)) return;
+
+    const contextText = await getContextForPrompt(ctx);
+    if (contextText) {
+      api.logger.info(`[claude-mem] Context injected via system prompt for agent=${ctx.agentId ?? "unknown"}`);
+      return { appendSystemContext: contextText };
     }
   });
 
   // ------------------------------------------------------------------
-  // Event: tool_result_persist — record tool observations + sync MEMORY.md
+  // Event: tool_result_persist — record tool observations
   // ------------------------------------------------------------------
   api.on("tool_result_persist", (event, ctx) => {
     api.logger.info(`[claude-mem] tool_result_persist fired: tool=${event.toolName ?? "unknown"} agent=${ctx.agentId ?? "none"} session=${ctx.sessionKey ?? "none"}`);
     const toolName = event.toolName;
     if (!toolName) return;
 
+    // Skip memory_ tools to prevent recursive observation loops
+    if (toolName.startsWith("memory_")) return;
+
     const contentSessionId = getContentSessionId(ctx.sessionKey);
 
     // Extract result text from all content blocks
@@ -654,7 +698,13 @@ export default function claudeMemPlugin(api: OpenClawPluginApi): void {
         .join("\n");
     }
 
-    // Fire-and-forget: send observation + sync MEMORY.md in parallel
+    // Truncate long responses to prevent oversized payloads
+    const MAX_TOOL_RESPONSE_LENGTH = 1000;
+    if (toolResponseText.length > MAX_TOOL_RESPONSE_LENGTH) {
+      toolResponseText = toolResponseText.slice(0, MAX_TOOL_RESPONSE_LENGTH);
+    }
+
+    // Fire-and-forget: send observation to worker
     workerPostFireAndForget(workerPort, "/api/sessions/observations", {
       contentSessionId,
       tool_name: toolName,
@@ -662,11 +712,6 @@ export default function claudeMemPlugin(api: OpenClawPluginApi): void {
       tool_response: toolResponseText,
       cwd: "",
     }, api.logger);
-
-    const workspaceDir = ctx.workspaceDir || workspaceDirsBySessionKey.get(ctx.sessionKey || "default");
-    if (syncMemoryFile && workspaceDir) {
-      syncMemoryToWorkspace(workspaceDir, ctx);
-    }
   });
 
   // ------------------------------------------------------------------
@@ -713,15 +758,14 @@ export default function claudeMemPlugin(api: OpenClawPluginApi): void {
   api.on("session_end", async (_event, ctx) => {
     const key = ctx.sessionKey || "default";
     sessionIds.delete(key);
-    workspaceDirsBySessionKey.delete(key);
   });
 
   // ------------------------------------------------------------------
   // Event: gateway_start — clear session tracking for fresh start
   // ------------------------------------------------------------------
   api.on("gateway_start", async () => {
-    workspaceDirsBySessionKey.clear();
     sessionIds.clear();
+    contextCache.clear();
     api.logger.info("[claude-mem] Gateway started — session tracking reset");
   });
 

package.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-mem",
-  "version": "10.2.1",
+  "version": "11.0.1",
   "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,14 +110,14 @@
   },
   "dependencies": {
     "@anthropic-ai/claude-agent-sdk": "^0.1.76",
+    "@clack/prompts": "^0.9.1",
     "@modelcontextprotocol/sdk": "^1.25.1",
-    "@chroma-core/default-embed": "^0.1.9",
     "ansi-to-html": "^0.7.2",
-    "chromadb": "^3.2.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",
@@ -118,9 +131,21 @@
     "@types/react": "^18.3.5",
     "@types/react-dom": "^18.3.0",
     "esbuild": "^0.27.2",
-    "node-addon-api": "^8.5.0",
     "np": "^11.0.2",
+    "tree-sitter-c": "^0.24.1",
+    "tree-sitter-cli": "^0.26.5",
+    "tree-sitter-cpp": "^0.23.4",
+    "tree-sitter-go": "^0.25.0",
+    "tree-sitter-java": "^0.23.5",
+    "tree-sitter-javascript": "^0.25.0",
+    "tree-sitter-python": "^0.25.0",
+    "tree-sitter-ruby": "^0.23.1",
+    "tree-sitter-rust": "^0.24.0",
+    "tree-sitter-typescript": "^0.23.2",
     "tsx": "^4.20.6",
     "typescript": "^5.3.0"
+  },
+  "optionalDependencies": {
+    "tree-kill": "^1.2.2"
   }
 }

plugin/.claude-plugin/plugin.json

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

plugin/commands/do.md

@@ -1,43 +0,0 @@
----
-description: "Execute a plan using subagents for implementation"
-argument-hint: "[task or plan reference]"
----
-
-You are an ORCHESTRATOR.
-
-Primary instruction: deploy subagents to execute *all* work for #$ARGUMENTS.
-Do not do the work yourself except to coordinate, route context, and verify that each subagent completed its assigned checklist.
-
-Deploy subagents to execute each phase of #$ARGUMENTS independently and consecutively. For every checklist item below, explicitly deploy (or reuse) a subagent responsible for that item and record its outcome before proceeding.
-
-## Execution Protocol (Orchestrator-Driven)
-
-Orchestrator rules:
-- Each phase uses fresh subagents where noted (or when context is large/unclear).
-- The orchestrator assigns one clear objective per subagent and requires evidence (commands run, outputs, files changed).
-- Do not advance to the next step until the assigned subagent reports completion and the orchestrator confirms it matches the plan.
-
-### During Each Phase:
-Deploy an "Implementation" subagent to:
-1. Execute the implementation as specified
-2. COPY patterns from documentation, don't invent
-3. Cite documentation sources in code comments when using unfamiliar APIs
-4. If an API seems missing, STOP and verify - don't assume it exists
-
-### After Each Phase:
-Deploy subagents for each post-phase responsibility:
-1. **Run verification checklist** - Deploy a "Verification" subagent to prove the phase worked
-2. **Anti-pattern check** - Deploy an "Anti-pattern" subagent to grep for known bad patterns from the plan
-3. **Code quality review** - Deploy a "Code Quality" subagent to review changes
-4. **Commit only if verified** - Deploy a "Commit" subagent *only after* verification passes; otherwise, do not commit
-
-### Between Phases:
-Deploy a "Branch/Sync" subagent to:
-- Push to working branch after each verified phase
-- Prepare the next phase handoff so the next phase's subagents start fresh but have plan context
-
-## Failure Modes to Prevent
-- Don't invent APIs that "should" exist - verify against docs
-- Don't add undocumented parameters - copy exact signatures
-- Don't skip verification - deploy a verification subagent and run the checklist
-- Don't commit before verification passes (or without explicit orchestrator approval)

plugin/commands/make-plan.md

@@ -1,66 +0,0 @@
----
-description: "Create an implementation plan with documentation discovery"
-argument-hint: "[feature or task description]"
----
-
-You are an ORCHESTRATOR.
-
-Create an LLM-friendly plan in phases that can be executed consecutively in new chat contexts.
-
-Delegation model (because subagents can under-report):
-- Use subagents for *fact gathering and extraction* (docs, examples, signatures, grep results).
-- Keep *synthesis and plan authoring* with the orchestrator (phase boundaries, task framing, final wording).
-- If a subagent report is incomplete or lacks evidence, the orchestrator must re-check with targeted reads/greps before finalizing the plan.
-
-Subagent reporting contract (MANDATORY):
-- Each subagent response must include:
-   1) Sources consulted (files/URLs) and what was read
-   2) Concrete findings (exact API names/signatures; exact file paths/locations)
-   3) Copy-ready snippet locations (example files/sections to copy)
-   4) "Confidence" note + known gaps (what might still be missing)
-- Reject and redeploy the subagent if it reports conclusions without sources.
-
-## Plan Structure Requirements
-
-### Phase 0: Documentation Discovery (ALWAYS FIRST)
-Before planning implementation, you MUST:
-Deploy one or more "Documentation Discovery" subagents to:
-1. Search for and read relevant documentation, examples, and existing patterns
-2. Identify the actual APIs, methods, and signatures available (not assumed)
-3. Create a brief "Allowed APIs" list citing specific documentation sources
-4. Note any anti-patterns to avoid (methods that DON'T exist, deprecated parameters)
-
-Then the orchestrator consolidates their findings into a single Phase 0 output.
-
-### Each Implementation Phase Must Include:
-1. **What to implement** - Frame tasks to COPY from docs, not transform existing code
-   - Good: "Copy the V2 session pattern from docs/examples.ts:45-60"
-   - Bad: "Migrate the existing code to V2"
-2. **Documentation references** - Cite specific files/lines for patterns to follow
-3. **Verification checklist** - How to prove this phase worked (tests, grep checks)
-4. **Anti-pattern guards** - What NOT to do (invented APIs, undocumented params)
-
-Subagent-friendly split:
-- Subagents can propose candidate doc references and verification commands.
-- The orchestrator must write the final phase text, ensuring tasks are copy-based, scoped, and independently executable.
-
-### Final Phase: Verification
-1. Verify all implementations match documentation
-2. Check for anti-patterns (grep for known bad patterns)
-3. Run tests to confirm functionality
-
-Delegation guidance:
-- Deploy a "Verification" subagent to draft the checklist and commands.
-- The orchestrator must review the checklist for completeness and ensure it maps to earlier phase outputs.
-
-## Key Principles
-- Documentation Availability ≠ Usage: Explicitly require reading docs
-- Task Framing Matters: Direct agents to docs, not just outcomes
-- Verify > Assume: Require proof, not assumptions about APIs
-- Session Boundaries: Each phase should be self-contained with its own doc references
-
-## Anti-Patterns to Prevent
-- Inventing API methods that "should" exist
-- Adding parameters not in documentation
-- Skipping verification steps
-- Assuming structure without checking examples

plugin/hooks/hooks.json

@@ -7,8 +7,8 @@
         "hooks": [
           {
             "type": "command",
-            "command": "${CLAUDE_PLUGIN_ROOT}/scripts/setup.sh",
-            "timeout": 120
+            "command": "_R=\"${CLAUDE_PLUGIN_ROOT}\"; [ -z \"$_R\" ] && _R=\"$HOME/.claude/plugins/marketplaces/thedotmack/plugin\"; \"$_R/scripts/setup.sh\"",
+            "timeout": 300
           }
         ]
       }
@@ -19,17 +19,17 @@
         "hooks": [
           {
             "type": "command",
-            "command": "node \"${CLAUDE_PLUGIN_ROOT}/scripts/smart-install.js\"",
+            "command": "_R=\"${CLAUDE_PLUGIN_ROOT}\"; [ -z \"$_R\" ] && _R=\"$HOME/.claude/plugins/marketplaces/thedotmack/plugin\"; node \"$_R/scripts/smart-install.js\"",
             "timeout": 300
           },
           {
             "type": "command",
-            "command": "node \"${CLAUDE_PLUGIN_ROOT}/scripts/bun-runner.js\" \"${CLAUDE_PLUGIN_ROOT}/scripts/worker-service.cjs\" start",
+            "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\" start",
             "timeout": 60
           },
           {
             "type": "command",
-            "command": "node \"${CLAUDE_PLUGIN_ROOT}/scripts/bun-runner.js\" \"${CLAUDE_PLUGIN_ROOT}/scripts/worker-service.cjs\" hook claude-code context",
+            "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 context",
             "timeout": 60
           }
         ]
@@ -40,12 +40,7 @@
         "hooks": [
           {
             "type": "command",
-            "command": "node \"${CLAUDE_PLUGIN_ROOT}/scripts/bun-runner.js\" \"${CLAUDE_PLUGIN_ROOT}/scripts/worker-service.cjs\" start",
-            "timeout": 60
-          },
-          {
-            "type": "command",
-            "command": "node \"${CLAUDE_PLUGIN_ROOT}/scripts/bun-runner.js\" \"${CLAUDE_PLUGIN_ROOT}/scripts/worker-service.cjs\" hook claude-code session-init",
+            "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-init",
             "timeout": 60
           }
         ]
@@ -57,12 +52,7 @@
         "hooks": [
           {
             "type": "command",
-            "command": "node \"${CLAUDE_PLUGIN_ROOT}/scripts/bun-runner.js\" \"${CLAUDE_PLUGIN_ROOT}/scripts/worker-service.cjs\" start",
-            "timeout": 60
-          },
-          {
-            "type": "command",
-            "command": "node \"${CLAUDE_PLUGIN_ROOT}/scripts/bun-runner.js\" \"${CLAUDE_PLUGIN_ROOT}/scripts/worker-service.cjs\" hook claude-code observation",
+            "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 observation",
             "timeout": 120
           }
         ]
@@ -73,18 +63,19 @@
         "hooks": [
           {
             "type": "command",
-            "command": "node \"${CLAUDE_PLUGIN_ROOT}/scripts/bun-runner.js\" \"${CLAUDE_PLUGIN_ROOT}/scripts/worker-service.cjs\" start",
-            "timeout": 60
-          },
-          {
-            "type": "command",
-            "command": "node \"${CLAUDE_PLUGIN_ROOT}/scripts/bun-runner.js\" \"${CLAUDE_PLUGIN_ROOT}/scripts/worker-service.cjs\" hook claude-code summarize",
+            "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 summarize",
             "timeout": 120
-          },
+          }
+        ]
+      }
+    ],
+    "SessionEnd": [
+      {
+        "hooks": [
           {
             "type": "command",
-            "command": "node \"${CLAUDE_PLUGIN_ROOT}/scripts/bun-runner.js\" \"${CLAUDE_PLUGIN_ROOT}/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/modes/code.json

@@ -87,8 +87,8 @@
     "system_identity": "You are a Claude-Mem, a specialized observer tool for creating searchable memory FOR FUTURE SESSIONS.\n\nCRITICAL: Record what was LEARNED/BUILT/FIXED/DEPLOYED/CONFIGURED, not what you (the observer) are doing.\n\nYou do not have access to tools. All information you need is provided in <observed_from_primary_session> messages. Create observations from what you observe - no investigation needed.",
     "spatial_awareness": "SPATIAL AWARENESS: Tool executions include the working directory (tool_cwd) to help you understand:\n- Which repository/project is being worked on\n- Where files are located relative to the project root\n- How to match requested paths to actual execution paths",
     "observer_role": "Your job is to monitor a different Claude Code session happening RIGHT NOW, with the goal of creating observations and progress summaries as the work is being done LIVE by the user. You are NOT the one doing the work - you are ONLY observing and recording what is being built, fixed, deployed, or configured in the other session.",
-    "recording_focus": "WHAT TO RECORD\n--------------\nFocus on deliverables and capabilities:\n- What the system NOW DOES differently (new capabilities)\n- What shipped to users/production (features, fixes, configs, docs)\n- Changes in technical domains (auth, data, UI, infra, DevOps, docs)\n\nUse verbs like: implemented, fixed, deployed, configured, migrated, optimized, added, refactored\n\n✅ GOOD EXAMPLES (describes what was built):\n- \"Authentication now supports OAuth2 with PKCE flow\"\n- \"Deployment pipeline runs canary releases with auto-rollback\"\n- \"Database indexes optimized for common query patterns\"\n\n❌ BAD EXAMPLES (describes observation process - DO NOT DO THIS):\n- \"Analyzed authentication implementation and stored findings\"\n- \"Tracked deployment steps and logged outcomes\"\n- \"Monitored database performance and recorded metrics\"",
-    "skip_guidance": "WHEN TO SKIP\n------------\nSkip routine operations:\n- Empty status checks\n- Package installations with no errors\n- Simple file listings\n- Repetitive operations you've already documented\n- If file related research comes back as empty or not found\n- **No output necessary if skipping.**",
+    "recording_focus": "WHAT TO RECORD\n--------------\nFocus on durable technical signal:\n- What the system NOW DOES differently (new capabilities)\n- What shipped to users/production (features, fixes, configs, docs)\n- Changes in technical domains (auth, data, UI, infra, DevOps, docs)\n- Concrete debugging or investigative findings from logs, traces, queue state, database rows, and code-path inspection\n\nUse verbs like: implemented, fixed, deployed, configured, migrated, optimized, added, refactored, discovered, confirmed, traced\n\n✅ GOOD EXAMPLES (describes what was built or learned):\n- \"Authentication now supports OAuth2 with PKCE flow\"\n- \"Deployment pipeline runs canary releases with auto-rollback\"\n- \"Database indexes optimized for common query patterns\"\n- \"Observation queue for claude-mem session timed out waiting for an agent pool slot\"\n- \"Fallback processing abandoned pending messages after Gemini and OpenRouter returned 404\"\n\n❌ BAD EXAMPLES (describes observation process - DO NOT DO THIS):\n- \"Analyzed authentication implementation and stored findings\"\n- \"Tracked deployment steps and logged outcomes\"\n- \"Monitored database performance and recorded metrics\"",
+    "skip_guidance": "WHEN TO SKIP\n------------\nSkip routine operations:\n- Empty status checks\n- Package installations with no errors\n- Simple file listings with no follow-on finding\n- Repetitive operations you've already documented\n- File related research that comes back empty or not found\n\nIf skipping, return an empty response only. Do not explain the skip in prose.",
     "type_guidance": "**type**: MUST be EXACTLY one of these 6 options (no other values allowed):\n      - bugfix: something was broken, now fixed\n      - feature: new capability or functionality added\n      - refactor: code restructured, behavior unchanged\n      - change: generic modification (docs, config, misc)\n      - discovery: learning about existing system\n      - decision: architectural/design choice with rationale",
     "concept_guidance": "**concepts**: 2-5 knowledge-type categories. MUST use ONLY these exact keywords:\n      - how-it-works: understanding mechanisms\n      - why-it-exists: purpose or rationale\n      - what-changed: modifications made\n      - problem-solution: issues and their fixes\n      - gotcha: traps or edge cases\n      - pattern: reusable approach\n      - trade-off: pros/cons of a decision\n\n    IMPORTANT: Do NOT include the observation type (change/discovery/decision) as a concept.\n    Types and concepts are separate dimensions.",
     "field_guidance": "**facts**: Concise, self-contained statements\nEach fact is ONE piece of information\n      No pronouns - each fact must stand alone\n      Include specific details: filenames, functions, values\n\n**files**: All files touched (full paths from project root)",
@@ -122,4 +122,4 @@
     "summary_format_instruction": "Respond in this XML format:",
     "summary_footer": "IMPORTANT! DO NOT do any work right now other than generating this next PROGRESS SUMMARY - and remember that you are a memory agent designed to summarize a DIFFERENT claude code session, not this one.\n\nNever reference yourself or your own actions. Do not output anything other than the summary content formatted in the XML structure above. All other output is ignored by the system, and the system has been designed to be smart about token usage. Please spend your tokens wisely on useful summary content.\n\nThank you, this summary will be very useful for keeping track of our progress!"
   }
-}
+}

plugin/modes/law-study--chill.json

@@ -0,0 +1,7 @@
+{
+  "name": "Law Study (Chill)",
+  "prompts": {
+    "recording_focus": "WHAT TO RECORD (HIGH SIGNAL ONLY)\n----------------------------------\nOnly record what would be painful to reconstruct later:\n- Issue-spotting triggers: specific fact patterns that signal a testable issue\n- Professor's explicit emphasis, frameworks, or exam tips\n- Counterintuitive holdings or gotchas that contradict intuition\n- Cross-case connections that reframe how a doctrine works\n- A synthesized rule only if it distills something non-obvious from multiple sources\n\nSkip anything that could be looked up in a casebook in under 60 seconds.\n\nUse verbs like: held, established, revealed, distinguished, flagged",
+    "skip_guidance": "WHEN TO SKIP (LIBERAL — WHEN IN DOUBT, SKIP)\n---------------------------------------------\nSkip freely:\n- All case briefs, even condensed ones, unless the holding is counterintuitive\n- Any rule or doctrine stated plainly in the casebook without nuance\n- Definitions of standard legal terms\n- Procedural history\n- Any fact pattern or case that wasn't specifically emphasized by the professor\n- Anything you could find again in under 60 seconds\n- **No output necessary if skipping.**"
+  }
+}

plugin/modes/law-study-CLAUDE.md

@@ -0,0 +1,85 @@
+# Legal Study Assistant
+
+You are a rigorous legal study partner for a law student. Your job is to help them understand the law deeply enough to reason through novel fact patterns independently on exams and in practice.
+
+---
+
+## Your Role
+
+- Help the student read, analyze, and extract meaning from legal documents
+- Ask questions that surface the student's reasoning, not just answers
+- Flag what matters for exams and what professors tend to emphasize
+- Push back when the student's analysis is imprecise or incomplete
+- Never write their exam answers — teach them to write their own
+
+---
+
+## Reading Cases Together
+
+When the student shares a case or document:
+
+1. Read it fully before saying anything. No skimming.
+2. Identify the procedural posture, then the issue, then the holding, then the reasoning.
+3. Separate holding from dicta explicitly — this distinction is always fair game.
+4. Surface ambiguity when the court was evasive. That ambiguity is often the exam question.
+5. Ask: "Which facts were outcome-determinative? What if those facts changed?"
+
+**Case briefs are always 3 sentences max:**
+> [Key facts that triggered the issue]. The court held [holding + extracted rule]. [Why this rule exists or how it fits the doctrine — only if non-obvious.]
+
+---
+
+## Critical Questions to Drive Analysis
+
+After reading any legal material, push the student to answer:
+
+- What is the rule stated as elements?
+- What did the dissent argue and why does it matter?
+- How does this fit — or conflict with — earlier cases?
+- What fact pattern on an exam triggers this rule?
+- What does the professor emphasize about this? Their framing is the exam framing.
+- Is the law settled or contested here?
+
+---
+
+## Issue Spotting
+
+When working through a fact pattern:
+
+1. Read the entire hypo before naming any issues.
+2. List every potential claim and defense — err toward inclusion.
+3. For each issue: rule → application to these specific facts → where the argument turns.
+4. Treat "irrelevant" facts as planted triggers. Nothing in an exam hypo is accidental.
+5. Calibrate to the professor's emphasis — they wrote the exam.
+
+---
+
+## Synthesizing Doctrine
+
+When pulling together multiple cases or a whole doctrine:
+
+1. Find the common principle across all the cases.
+2. Build the rule as a spectrum or taxonomy when cases represent different scenarios.
+3. State the limiting principle — where does this rule stop and why.
+4. Majority rule first, then minority positions with their rationale.
+5. Identify the live tension — what the courts haven't resolved yet.
+
+---
+
+## Tone and Pace
+
+- Be direct. Law school trains precision — model it.
+- When the student is vague, say so and ask them to be specific.
+- Celebrate when they spot something sharp. Legal reasoning is hard.
+- Match the student's pace — deep dive when they want to go deep, quick synthesis when they're reviewing.
+
+---
+
+## Starting a Session
+
+The student should tell you:
+- Which course this is for
+- What material they're working through (cases, statute, doctrine, hypo practice)
+- What kind of help they want: deep analysis, synthesis, issue spotting, or exam review
+
+Example: *"Contracts — working through consideration doctrine. Here are four cases. Help me find the through-line and identify what patterns trigger the issue on an exam."*

plugin/modes/law-study.json

@@ -0,0 +1,120 @@
+{
+  "name": "Law Study",
+  "description": "Legal study and exam preparation for law students",
+  "version": "1.0.0",
+  "observation_types": [
+    {
+      "id": "case-holding",
+      "label": "Case Holding",
+      "description": "Case brief (2-3 sentences: key facts + holding) with extracted legal rule",
+      "emoji": "⚖️",
+      "work_emoji": "📖"
+    },
+    {
+      "id": "issue-pattern",
+      "label": "Issue Pattern",
+      "description": "Exam trigger or fact pattern that signals a legal issue to spot",
+      "emoji": "🎯",
+      "work_emoji": "🔍"
+    },
+    {
+      "id": "prof-framework",
+      "label": "Prof Framework",
+      "description": "Professor's analytical lens, emphasis, or approach to a topic or doctrine",
+      "emoji": "🧑‍🏫",
+      "work_emoji": "📝"
+    },
+    {
+      "id": "doctrine-rule",
+      "label": "Doctrine / Rule",
+      "description": "Legal test, standard, or doctrine synthesized from cases, statutes, or restatements",
+      "emoji": "📜",
+      "work_emoji": "🔍"
+    },
+    {
+      "id": "argument-structure",
+      "label": "Argument Structure",
+      "description": "Legal argument or counter-argument worked through with analytical steps",
+      "emoji": "🗣️",
+      "work_emoji": "⚖️"
+    },
+    {
+      "id": "cross-case-connection",
+      "label": "Cross-Case Connection",
+      "description": "Insight linking multiple cases, doctrines, or topics that reveals a deeper principle",
+      "emoji": "🔗",
+      "work_emoji": "🔍"
+    }
+  ],
+  "observation_concepts": [
+    {
+      "id": "exam-relevant",
+      "label": "Exam Relevant",
+      "description": "Flagged by professor or likely to appear on exams based on emphasis"
+    },
+    {
+      "id": "minority-position",
+      "label": "Minority Position",
+      "description": "Dissent, minority rule, or alternative jurisdictional approach worth knowing"
+    },
+    {
+      "id": "gotcha",
+      "label": "Gotcha",
+      "description": "Subtle nuance, counterintuitive result, or common mistake students get wrong"
+    },
+    {
+      "id": "unsettled-law",
+      "label": "Unsettled Law",
+      "description": "Circuit split, open question, or evolving area of law"
+    },
+    {
+      "id": "policy-rationale",
+      "label": "Policy Rationale",
+      "description": "Normative or policy argument underlying a rule or holding"
+    },
+    {
+      "id": "course-theme",
+      "label": "Course Theme",
+      "description": "How this case or rule connects to the overarching narrative or theory of the course"
+    }
+  ],
+  "prompts": {
+    "system_identity": "You are Claude-Mem, a specialized observer tool for creating searchable memory FOR FUTURE SESSIONS.\n\nCRITICAL: Record what was READ, ANALYZED, SYNTHESIZED, or LEARNED about the law, not what you (the observer) are doing.\n\nYou do not have access to tools. All information you need is provided in <observed_from_primary_session> messages. Create observations from what you observe - no investigation needed.",
+    "spatial_awareness": "SPATIAL AWARENESS: Tool executions include the working directory (tool_cwd) to help you understand:\n- Which repository/project is being worked on\n- Where files are located relative to the project root\n- How to match requested paths to actual execution paths",
+    "observer_role": "Your job is to monitor a different Claude Code session happening RIGHT NOW, with the goal of creating observations and progress summaries as legal study is being done LIVE by the user. You are NOT the one doing the work - you are ONLY observing and recording what is being read, analyzed, briefed, or synthesized in the other session.",
+    "recording_focus": "WHAT TO RECORD\n--------------\nFocus on legal knowledge and exam-ready insights:\n- Case holdings distilled to 2-3 sentences (key facts + holding + rule)\n- Legal tests, elements, and standards extracted from cases or statutes\n- Issue-spotting triggers: what fact patterns signal which legal issues\n- Professor's framing, emphasis, or analytical approach to a doctrine\n- Arguments and counter-arguments worked through\n- Connections across cases or doctrines that reveal underlying principles\n\nUse verbs like: held, established, synthesized, identified, distinguished, analyzed, revealed, connected\n\n✅ GOOD EXAMPLES (describes what was learned about the law):\n- \"Palsgraf established proximate cause requires the harm be foreseeable to the defendant at the time of conduct\"\n- \"Prof frames consideration doctrine around the bargain theory, not benefit-detriment — exam answers should reflect this\"\n- \"When fact pattern shows concurrent causation, issue-spot both but-for AND substantial factor tests\"\n\n❌ BAD EXAMPLES (describes observation process - DO NOT DO THIS):\n- \"Analyzed the case and recorded findings about proximate cause\"\n- \"Tracked professor's comments and stored the framework\"\n- \"Monitored discussion of consideration and noted the approach\"",
+    "skip_guidance": "WHEN TO SKIP\n------------\nSkip these — not worth recording:\n- Full case briefs (only record the 2-3 sentence distilled version with the rule)\n- Re-reading the same case or passage without new insight\n- Definitions of basic terms the student already knows\n- Routine case brief formatting with no analytical content\n- Simple fact summaries that don't extract a rule or pattern\n- Procedural history details not relevant to the legal rule\n- **No output necessary if skipping.**",
+    "type_guidance": "**type**: MUST be EXACTLY one of these 6 options (no other values allowed):\n      - case-holding: case brief (2-3 sentences: key facts + holding) with extracted legal rule\n      - issue-pattern: exam trigger or fact pattern that signals a legal issue to spot\n      - prof-framework: professor's analytical lens, emphasis, or approach to a topic or doctrine\n      - doctrine-rule: legal test, standard, or doctrine synthesized from cases, statutes, or restatements\n      - argument-structure: legal argument or counter-argument worked through with analytical steps\n      - cross-case-connection: insight linking multiple cases, doctrines, or topics that reveals a deeper principle",
+    "concept_guidance": "**concepts**: 2-5 knowledge-type categories. MUST use ONLY these exact keywords:\n      - exam-relevant: flagged by professor or likely to appear on exams\n      - minority-position: dissent, minority rule, or alternative jurisdictional approach\n      - gotcha: subtle nuance, counterintuitive result, or common mistake\n      - unsettled-law: circuit split, open question, or evolving area\n      - policy-rationale: normative or policy argument underlying a rule\n      - course-theme: connects to the overarching narrative or theory of the course\n\n    IMPORTANT: Do NOT include the observation type (case-holding/issue-pattern/etc.) as a concept.\n    Types and concepts are separate dimensions.",
+    "field_guidance": "**facts**: Concise, self-contained statements\nEach fact is ONE piece of information\n      No pronouns - each fact must stand alone\n      Include specific details: case names, rule elements, test names, jurisdiction\n\n**files**: All files or documents read (full paths from project root)",
+    "output_format_header": "OUTPUT FORMAT\n-------------\nOutput observations using this XML structure:",
+    "format_examples": "",
+    "footer": "IMPORTANT! DO NOT do any work right now other than generating this OBSERVATIONS from tool use messages - and remember that you are a memory agent designed to summarize a DIFFERENT claude code session, not this one.\n\nNever reference yourself or your own actions. Do not output anything other than the observation content formatted in the XML structure above. All other output is ignored by the system, and the system has been designed to be smart about token usage. Please spend your tokens wisely on useful observations.\n\nRemember that we record these observations as a way of helping us stay on track with our progress, and to help us keep important decisions and changes at the forefront of our minds! :) Thank you so much for your help!",
+
+    "xml_title_placeholder": "[**title**: Case name, doctrine name, or short description of the legal insight]",
+    "xml_subtitle_placeholder": "[**subtitle**: One sentence capturing the core legal rule or exam relevance (max 24 words)]",
+    "xml_fact_placeholder": "[Concise, self-contained legal fact — include case names, rule elements, test names]",
+    "xml_narrative_placeholder": "[**narrative**: Full legal context: what the case held or rule requires, how it connects to other doctrine, why it matters for exams or practice]",
+    "xml_concept_placeholder": "[exam-relevant | minority-position | gotcha | unsettled-law | policy-rationale | course-theme]",
+    "xml_file_placeholder": "[path/to/document]",
+
+    "xml_summary_request_placeholder": "[Short title capturing the legal topic studied AND what was analyzed or synthesized]",
+    "xml_summary_investigated_placeholder": "[What cases, statutes, or doctrines were read or examined in this session?]",
+    "xml_summary_learned_placeholder": "[What legal rules, patterns, or frameworks were extracted and understood?]",
+    "xml_summary_completed_placeholder": "[What study work was completed? Which cases briefed, which doctrines synthesized, which issue patterns identified?]",
+    "xml_summary_next_steps_placeholder": "[What topics, cases, or doctrines are being studied next in this session?]",
+    "xml_summary_notes_placeholder": "[Additional insights about exam strategy, professor emphasis, or cross-topic connections observed in this session]",
+
+    "header_memory_start": "LAW STUDY MEMORY START\n=======================",
+    "header_memory_continued": "LAW STUDY MEMORY CONTINUED\n===========================",
+    "header_summary_checkpoint": "LAW STUDY SUMMARY CHECKPOINT\n============================",
+
+    "continuation_greeting": "Hello memory agent, you are continuing to observe the primary Claude session doing legal study and case analysis.",
+    "continuation_instruction": "IMPORTANT: Continue generating observations from tool use messages using the XML structure below.",
+
+    "summary_instruction": "Write progress notes of what legal material was studied, what rules and patterns were extracted, and what's next. This is a checkpoint to capture study progress so far. The session is ongoing - more cases or doctrines may be analyzed after this summary. Write \"next_steps\" as the current study trajectory (what topics or cases are actively being worked through), not as post-session plans. Always write at least a minimal summary explaining current progress, even if study is still early, so that users see a summary output tied to each study block.",
+    "summary_context_label": "Claude's Full Response to User:",
+    "summary_format_instruction": "Respond in this XML format:",
+    "summary_footer": "IMPORTANT! DO NOT do any work right now other than generating this next PROGRESS SUMMARY - and remember that you are a memory agent designed to summarize a DIFFERENT claude code session, not this one.\n\nNever reference yourself or your own actions. Do not output anything other than the summary content formatted in the XML structure above. All other output is ignored by the system, and the system has been designed to be smart about token usage. Please spend your tokens wisely on useful summary content.\n\nThank you, this summary will be very useful for keeping track of legal study progress!"
+  }
+}

plugin/package.json

@@ -1,11 +1,20 @@
 {
   "name": "claude-mem-plugin",
-  "version": "10.2.1",
+  "version": "11.0.1",
   "private": true,
   "description": "Runtime dependencies for claude-mem bundled hooks",
   "type": "module",
   "dependencies": {
-    "@chroma-core/default-embed": "^0.1.9"
+    "tree-sitter-cli": "^0.26.5",
+    "tree-sitter-c": "^0.24.1",
+    "tree-sitter-cpp": "^0.23.4",
+    "tree-sitter-go": "^0.25.0",
+    "tree-sitter-java": "^0.23.5",
+    "tree-sitter-javascript": "^0.25.0",
+    "tree-sitter-python": "^0.25.0",
+    "tree-sitter-ruby": "^0.23.1",
+    "tree-sitter-rust": "^0.24.0",
+    "tree-sitter-typescript": "^0.23.2"
   },
   "engines": {
     "node": ">=18.0.0",

plugin/scripts/CLAUDE.md

@@ -1,3 +1,5 @@
+Never read built source files in this directory. These are compiled outputs — read the source files in `src/` instead.
+
 <claude-mem-context>
 # Recent Activity
 

plugin/scripts/bun-runner.js

@@ -12,12 +12,37 @@
  * Fixes #818: Worker fails to start on fresh install
  */
 import { spawnSync, spawn } from 'child_process';
-import { existsSync } from 'fs';
-import { join } from 'path';
+import { existsSync, readFileSync } from 'fs';
+import { join, dirname, resolve } from 'path';
 import { homedir } from 'os';
+import { fileURLToPath } from 'url';
 
 const IS_WINDOWS = process.platform === 'win32';
 
+// Self-resolve plugin root when CLAUDE_PLUGIN_ROOT is not set by Claude Code.
+// Upstream bug: anthropics/claude-code#24529 — Stop hooks (and on Linux, all hooks)
+// don't receive CLAUDE_PLUGIN_ROOT, causing script paths to resolve to /scripts/...
+// which doesn't exist. This fallback derives the plugin root from bun-runner.js's
+// own filesystem location (this file lives in <plugin-root>/scripts/).
+const __bun_runner_dirname = dirname(fileURLToPath(import.meta.url));
+const RESOLVED_PLUGIN_ROOT = process.env.CLAUDE_PLUGIN_ROOT || resolve(__bun_runner_dirname, '..');
+
+/**
+ * Fix script path arguments that were broken by empty CLAUDE_PLUGIN_ROOT.
+ * When CLAUDE_PLUGIN_ROOT is empty, "${CLAUDE_PLUGIN_ROOT}/scripts/foo.cjs"
+ * expands to "/scripts/foo.cjs" which doesn't exist. Detect this and rewrite
+ * the path using our self-resolved plugin root.
+ */
+function fixBrokenScriptPath(argPath) {
+  if (argPath.startsWith('/scripts/') && !existsSync(argPath)) {
+    const fixedPath = join(RESOLVED_PLUGIN_ROOT, argPath);
+    if (existsSync(fixedPath)) {
+      return fixedPath;
+    }
+  }
+  return argPath;
+}
+
 /**
  * Find Bun executable - checks PATH first, then common install locations
  */
@@ -54,6 +79,24 @@ function findBun() {
   return null;
 }
 
+// Early exit if plugin is disabled in Claude Code settings (#781).
+// Sync read + JSON parse — fastest possible check before spawning Bun.
+function isPluginDisabledInClaudeSettings() {
+  try {
+    const configDir = process.env.CLAUDE_CONFIG_DIR || join(homedir(), '.claude');
+    const settingsPath = join(configDir, 'settings.json');
+    if (!existsSync(settingsPath)) return false;
+    const settings = JSON.parse(readFileSync(settingsPath, 'utf-8'));
+    return settings?.enabledPlugins?.['claude-mem@thedotmack'] === false;
+  } catch {
+    return false;
+  }
+}
+
+if (isPluginDisabledInClaudeSettings()) {
+  process.exit(0);
+}
+
 // Get args: node bun-runner.js <script> [args...]
 const args = process.argv.slice(2);
 
@@ -62,6 +105,9 @@ if (args.length === 0) {
   process.exit(1);
 }
 
+// Fix broken script paths caused by empty CLAUDE_PLUGIN_ROOT (#1215)
+args[0] = fixBrokenScriptPath(args[0]);
+
 const bunPath = findBun();
 
 if (!bunPath) {

plugin/scripts/setup.sh

@@ -1,228 +0,0 @@
-#!/usr/bin/env bash
-#
-# claude-mem Setup Hook
-# Ensures dependencies are installed before plugin runs
-#
-
-set -euo pipefail
-
-# Use CLAUDE_PLUGIN_ROOT if available, otherwise detect from script location
-if [[ -z "${CLAUDE_PLUGIN_ROOT:-}" ]]; then
-  SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
-  ROOT="$(dirname "$SCRIPT_DIR")"
-else
-  ROOT="$CLAUDE_PLUGIN_ROOT"
-fi
-
-MARKER="$ROOT/.install-version"
-PKG_JSON="$ROOT/package.json"
-
-# Colors (when terminal supports it)
-if [[ -t 2 ]]; then
-  RED='\033[0;31m'
-  GREEN='\033[0;32m'
-  YELLOW='\033[0;33m'
-  BLUE='\033[0;34m'
-  NC='\033[0m' # No Color
-else
-  RED='' GREEN='' YELLOW='' BLUE='' NC=''
-fi
-
-log_info()  { echo -e "${BLUE}ℹ${NC} $*" >&2; }
-log_ok()    { echo -e "${GREEN}✓${NC} $*" >&2; }
-log_warn()  { echo -e "${YELLOW}⚠${NC} $*" >&2; }
-log_error() { echo -e "${RED}✗${NC} $*" >&2; }
-
-#
-# Detect Bun - check PATH and common locations
-#
-find_bun() {
-  # Try PATH first
-  if command -v bun &>/dev/null; then
-    echo "bun"
-    return 0
-  fi
-  
-  # Check common install locations
-  local paths=(
-    "$HOME/.bun/bin/bun"
-    "/usr/local/bin/bun"
-    "/opt/homebrew/bin/bun"
-  )
-  
-  for p in "${paths[@]}"; do
-    if [[ -x "$p" ]]; then
-      echo "$p"
-      return 0
-    fi
-  done
-  
-  return 1
-}
-
-#
-# Detect uv - check PATH and common locations
-#
-find_uv() {
-  # Try PATH first
-  if command -v uv &>/dev/null; then
-    echo "uv"
-    return 0
-  fi
-  
-  # Check common install locations
-  local paths=(
-    "$HOME/.local/bin/uv"
-    "$HOME/.cargo/bin/uv"
-    "/usr/local/bin/uv"
-    "/opt/homebrew/bin/uv"
-  )
-  
-  for p in "${paths[@]}"; do
-    if [[ -x "$p" ]]; then
-      echo "$p"
-      return 0
-    fi
-  done
-  
-  return 1
-}
-
-#
-# Get package.json version
-#
-get_pkg_version() {
-  if [[ -f "$PKG_JSON" ]]; then
-    # Simple grep-based extraction (no jq dependency)
-    grep -o '"version"[[:space:]]*:[[:space:]]*"[^"]*"' "$PKG_JSON" | head -1 | sed 's/.*"\([^"]*\)"$/\1/'
-  fi
-}
-
-#
-# Get marker version (if exists)
-#
-get_marker_version() {
-  if [[ -f "$MARKER" ]]; then
-    grep -o '"version"[[:space:]]*:[[:space:]]*"[^"]*"' "$MARKER" | head -1 | sed 's/.*"\([^"]*\)"$/\1/'
-  fi
-}
-
-#
-# Get marker's recorded bun version
-#
-get_marker_bun() {
-  if [[ -f "$MARKER" ]]; then
-    grep -o '"bun"[[:space:]]*:[[:space:]]*"[^"]*"' "$MARKER" | head -1 | sed 's/.*"\([^"]*\)"$/\1/'
-  fi
-}
-
-#
-# Check if install is needed
-#
-needs_install() {
-  # No node_modules? Definitely need install
-  if [[ ! -d "$ROOT/node_modules" ]]; then
-    return 0
-  fi
-  
-  # No marker? Need install
-  if [[ ! -f "$MARKER" ]]; then
-    return 0
-  fi
-  
-  local pkg_ver marker_ver bun_ver marker_bun
-  pkg_ver=$(get_pkg_version)
-  marker_ver=$(get_marker_version)
-  
-  # Version mismatch? Need install
-  if [[ "$pkg_ver" != "$marker_ver" ]]; then
-    return 0
-  fi
-  
-  # Bun version changed? Need install
-  if BUN_PATH=$(find_bun); then
-    bun_ver=$("$BUN_PATH" --version 2>/dev/null || echo "")
-    marker_bun=$(get_marker_bun)
-    if [[ -n "$bun_ver" && "$bun_ver" != "$marker_bun" ]]; then
-      return 0
-    fi
-  fi
-  
-  # All good, no install needed
-  return 1
-}
-
-#
-# Write version marker after successful install
-#
-write_marker() {
-  local bun_ver uv_ver pkg_ver
-  pkg_ver=$(get_pkg_version)
-  bun_ver=$("$BUN_PATH" --version 2>/dev/null || echo "unknown")
-  
-  if UV_PATH=$(find_uv); then
-    uv_ver=$("$UV_PATH" --version 2>/dev/null | head -1 || echo "unknown")
-  else
-    uv_ver="not-installed"
-  fi
-  
-  cat > "$MARKER" <<EOF
-{
-  "version": "$pkg_ver",
-  "bun": "$bun_ver",
-  "uv": "$uv_ver",
-  "installedAt": "$(date -u +%Y-%m-%dT%H:%M:%SZ)"
-}
-EOF
-}
-
-#
-# Main
-#
-
-# 1. Check for Bun
-BUN_PATH=$(find_bun) || true
-if [[ -z "$BUN_PATH" ]]; then
-  log_error "Bun runtime not found!"
-  echo "" >&2
-  echo "claude-mem requires Bun to run. Please install it:" >&2
-  echo "" >&2
-  echo "  curl -fsSL https://bun.sh/install | bash" >&2
-  echo "" >&2
-  echo "Or on macOS with Homebrew:" >&2
-  echo "" >&2
-  echo "  brew install oven-sh/bun/bun" >&2
-  echo "" >&2
-  echo "Then restart your terminal and try again." >&2
-  exit 1
-fi
-
-BUN_VERSION=$("$BUN_PATH" --version 2>/dev/null || echo "unknown")
-log_ok "Bun $BUN_VERSION found at $BUN_PATH"
-
-# 2. Check for uv (optional - for Python/Chroma support)
-UV_PATH=$(find_uv) || true
-if [[ -z "$UV_PATH" ]]; then
-  log_warn "uv not found (optional - needed for Python/Chroma vector search)"
-  echo "  To install: curl -LsSf https://astral.sh/uv/install.sh | sh" >&2
-else
-  UV_VERSION=$("$UV_PATH" --version 2>/dev/null | head -1 || echo "unknown")
-  log_ok "uv $UV_VERSION found"
-fi
-
-# 3. Install dependencies if needed
-if needs_install; then
-  log_info "Installing dependencies with Bun..."
-  
-  if ! "$BUN_PATH" install --cwd "$ROOT"; then
-    log_error "Failed to install dependencies"
-    exit 1
-  fi
-  
-  write_marker
-  log_ok "Dependencies installed ($(get_pkg_version))"
-else
-  log_ok "Dependencies up to date ($(get_marker_version))"
-fi
-
-exit 0

plugin/scripts/smart-install.js

@@ -4,16 +4,72 @@
  *
  * Ensures Bun runtime and uv (Python package manager) are installed
  * (auto-installs if missing) and handles dependency installation when needed.
+ *
+ * Resolves the install directory from CLAUDE_PLUGIN_ROOT (set by Claude Code
+ * for both cache and marketplace installs), falling back to script location
+ * and legacy paths.
  */
 import { existsSync, readFileSync, writeFileSync } from 'fs';
 import { execSync, spawnSync } from 'child_process';
-import { join } from 'path';
+import { join, dirname } from 'path';
 import { homedir } from 'os';
+import { fileURLToPath } from 'url';
 
-const ROOT = join(homedir(), '.claude', 'plugins', 'marketplaces', 'thedotmack');
-const MARKER = join(ROOT, '.install-version');
+// Early exit if plugin is disabled in Claude Code settings (#781)
+function isPluginDisabledInClaudeSettings() {
+  try {
+    const configDir = process.env.CLAUDE_CONFIG_DIR || join(homedir(), '.claude');
+    const settingsPath = join(configDir, 'settings.json');
+    if (!existsSync(settingsPath)) return false;
+    const settings = JSON.parse(readFileSync(settingsPath, 'utf-8'));
+    return settings?.enabledPlugins?.['claude-mem@thedotmack'] === false;
+  } catch {
+    return false;
+  }
+}
+
+if (isPluginDisabledInClaudeSettings()) {
+  process.exit(0);
+}
 const IS_WINDOWS = process.platform === 'win32';
 
+/**
+ * Resolve the plugin root directory where dependencies should be installed.
+ *
+ * Priority:
+ * 1. CLAUDE_PLUGIN_ROOT env var (set by Claude Code for hooks — works for
+ *    both cache-based and marketplace installs)
+ * 2. Script location (dirname of this file, up one level from scripts/)
+ * 3. XDG path (~/.config/claude/plugins/marketplaces/thedotmack)
+ * 4. Legacy path (~/.claude/plugins/marketplaces/thedotmack)
+ */
+function resolveRoot() {
+  // CLAUDE_PLUGIN_ROOT is the authoritative location set by Claude Code
+  if (process.env.CLAUDE_PLUGIN_ROOT) {
+    const root = process.env.CLAUDE_PLUGIN_ROOT;
+    if (existsSync(join(root, 'package.json'))) return root;
+  }
+
+  // Derive from script location (this file is in <root>/scripts/)
+  try {
+    const scriptDir = dirname(fileURLToPath(import.meta.url));
+    const candidate = dirname(scriptDir);
+    if (existsSync(join(candidate, 'package.json'))) return candidate;
+  } catch {
+    // import.meta.url not available
+  }
+
+  // Probe XDG path, then legacy
+  const marketplaceRel = join('plugins', 'marketplaces', 'thedotmack');
+  const xdg = join(homedir(), '.config', 'claude', marketplaceRel);
+  if (existsSync(join(xdg, 'package.json'))) return xdg;
+
+  return join(homedir(), '.claude', marketplaceRel);
+}
+
+const ROOT = resolveRoot();
+const MARKER = join(ROOT, '.install-version');
+
 /**
  * Check if Bun is installed and accessible
  */
@@ -164,14 +220,14 @@ function installBun() {
       // Windows: Use PowerShell installer
       console.error('   Installing via PowerShell...');
       execSync('powershell -c "irm bun.sh/install.ps1 | iex"', {
-        stdio: 'inherit',
+        stdio: ['pipe', 'pipe', 'inherit'],
         shell: true
       });
     } else {
       // Unix/macOS: Use curl installer
       console.error('   Installing via curl...');
       execSync('curl -fsSL https://bun.sh/install | bash', {
-        stdio: 'inherit',
+        stdio: ['pipe', 'pipe', 'inherit'],
         shell: true
       });
     }
@@ -229,14 +285,14 @@ function installUv() {
       // Windows: Use PowerShell installer
       console.error('   Installing via PowerShell...');
       execSync('powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"', {
-        stdio: 'inherit',
+        stdio: ['pipe', 'pipe', 'inherit'],
         shell: true
       });
     } else {
       // Unix/macOS: Use curl installer
       console.error('   Installing via curl...');
       execSync('curl -LsSf https://astral.sh/uv/install.sh | sh', {
-        stdio: 'inherit',
+        stdio: ['pipe', 'pipe', 'inherit'],
         shell: true
       });
     }
@@ -287,7 +343,7 @@ function installUv() {
  * Add shell alias for claude-mem command
  */
 function installCLI() {
-  const WORKER_CLI = join(ROOT, 'plugin', 'scripts', 'worker-service.cjs');
+  const WORKER_CLI = join(ROOT, 'scripts', 'worker-service.cjs');
   const bunPath = getBunPath() || 'bun';
   const aliasLine = `alias claude-mem='${bunPath} "${WORKER_CLI}"'`;
   const markerPath = join(ROOT, '.cli-installed');
@@ -370,14 +426,18 @@ function installDeps() {
   // Quote path for Windows paths with spaces
   const bunCmd = IS_WINDOWS && bunPath.includes(' ') ? `"${bunPath}"` : bunPath;
 
+  // Use pipe for stdout to prevent non-JSON output leaking to Claude Code hooks.
+  // stderr is inherited so progress/errors are still visible to the user.
+  const installStdio = ['pipe', 'pipe', 'inherit'];
+
   let bunSucceeded = false;
   try {
-    execSync(`${bunCmd} install`, { cwd: ROOT, stdio: 'inherit', shell: IS_WINDOWS });
+    execSync(`${bunCmd} install`, { cwd: ROOT, stdio: installStdio, shell: IS_WINDOWS });
     bunSucceeded = true;
   } catch {
     // First attempt failed, try with force flag
     try {
-      execSync(`${bunCmd} install --force`, { cwd: ROOT, stdio: 'inherit', shell: IS_WINDOWS });
+      execSync(`${bunCmd} install --force`, { cwd: ROOT, stdio: installStdio, shell: IS_WINDOWS });
       bunSucceeded = true;
     } catch {
       // Bun failed completely, will try npm fallback
@@ -389,7 +449,7 @@ function installDeps() {
     console.error('⚠️  Bun install failed, falling back to npm...');
     console.error('   (This can happen with npm alias packages like *-cjs)');
     try {
-      execSync('npm install', { cwd: ROOT, stdio: 'inherit', shell: IS_WINDOWS });
+      execSync('npm install', { cwd: ROOT, stdio: installStdio, shell: IS_WINDOWS });
     } catch (npmError) {
       throw new Error('Both bun and npm install failed: ' + npmError.message);
     }
@@ -405,6 +465,31 @@ function installDeps() {
   }));
 }
 
+/**
+ * Verify that critical runtime modules are resolvable from the install directory.
+ * Returns true if all critical modules exist, false otherwise.
+ */
+function verifyCriticalModules() {
+  const pkg = JSON.parse(readFileSync(join(ROOT, 'package.json'), 'utf-8'));
+  const dependencies = Object.keys(pkg.dependencies || {});
+
+  const missing = [];
+  for (const dep of dependencies) {
+    // Check that the module directory exists in node_modules
+    const modulePath = join(ROOT, 'node_modules', ...dep.split('/'));
+    if (!existsSync(modulePath)) {
+      missing.push(dep);
+    }
+  }
+
+  if (missing.length > 0) {
+    console.error(`❌ Post-install check failed: missing modules: ${missing.join(', ')}`);
+    return false;
+  }
+
+  return true;
+}
+
 // Main execution
 try {
   // Step 1: Ensure Bun is installed and meets minimum version (REQUIRED)
@@ -425,7 +510,7 @@ try {
     console.error(`⚠️  Bun ${currentVersion} is outdated. Minimum required: ${MIN_BUN_VERSION}`);
     console.error('   Upgrading bun...');
     try {
-      execSync('bun upgrade', { stdio: 'inherit', shell: IS_WINDOWS });
+      execSync('bun upgrade', { stdio: ['pipe', 'pipe', 'inherit'], shell: IS_WINDOWS });
       if (!isBunVersionSufficient()) {
         console.error(`❌ Bun upgrade failed. Please manually upgrade: bun upgrade`);
         process.exit(1);
@@ -456,6 +541,21 @@ try {
     const newVersion = pkg.version;
 
     installDeps();
+
+    // Verify critical modules are resolvable
+    if (!verifyCriticalModules()) {
+      console.error('⚠️  Retrying install with npm...');
+      try {
+        execSync('npm install --production', { cwd: ROOT, stdio: ['pipe', 'pipe', 'inherit'], shell: IS_WINDOWS });
+      } catch {
+        // npm also failed
+      }
+      if (!verifyCriticalModules()) {
+        console.error('❌ Dependencies could not be installed. Plugin may not work correctly.');
+        process.exit(1);
+      }
+    }
+
     console.error('✅ Dependencies installed');
 
     // Auto-restart worker to pick up new code
@@ -481,7 +581,12 @@ try {
 
   // Step 4: Install CLI to PATH
   installCLI();
+
+  // Output valid JSON for Claude Code hook contract
+  console.log(JSON.stringify({ continue: true, suppressOutput: true }));
 } catch (e) {
   console.error('❌ Installation failed:', e.message);
+  // Still output valid JSON so Claude Code doesn't show a confusing error
+  console.log(JSON.stringify({ continue: true, suppressOutput: true }));
   process.exit(1);
 }

plugin/skills/do/SKILL.md

@@ -1,5 +1,5 @@
 ---
-name: do-plan
+name: do
 description: Execute a phased implementation plan using subagents. Use when asked to execute, run, or carry out a plan — especially one created by make-plan.
 ---
 

plugin/skills/make-plan/SKILL.md

@@ -0,0 +1,63 @@
+---
+name: make-plan
+description: Create a detailed, phased implementation plan with documentation discovery. Use when asked to plan a feature, task, or multi-step implementation — especially before executing with do.
+---
+
+# Make Plan
+
+You are an ORCHESTRATOR. Create an LLM-friendly plan in phases that can be executed consecutively in new chat contexts.
+
+## Delegation Model
+
+Use subagents for *fact gathering and extraction* (docs, examples, signatures, grep results). Keep *synthesis and plan authoring* with the orchestrator (phase boundaries, task framing, final wording). If a subagent report is incomplete or lacks evidence, re-check with targeted reads/greps before finalizing.
+
+### Subagent Reporting Contract (MANDATORY)
+
+Each subagent response must include:
+1. Sources consulted (files/URLs) and what was read
+2. Concrete findings (exact API names/signatures; exact file paths/locations)
+3. Copy-ready snippet locations (example files/sections to copy)
+4. "Confidence" note + known gaps (what might still be missing)
+
+Reject and redeploy the subagent if it reports conclusions without sources.
+
+## Plan Structure
+
+### Phase 0: Documentation Discovery (ALWAYS FIRST)
+
+Before planning implementation, deploy "Documentation Discovery" subagents to:
+1. Search for and read relevant documentation, examples, and existing patterns
+2. Identify the actual APIs, methods, and signatures available (not assumed)
+3. Create a brief "Allowed APIs" list citing specific documentation sources
+4. Note any anti-patterns to avoid (methods that DON'T exist, deprecated parameters)
+
+The orchestrator consolidates findings into a single Phase 0 output.
+
+### Each Implementation Phase Must Include
+
+1. **What to implement** — Frame tasks to COPY from docs, not transform existing code
+   - Good: "Copy the V2 session pattern from docs/examples.ts:45-60"
+   - Bad: "Migrate the existing code to V2"
+2. **Documentation references** — Cite specific files/lines for patterns to follow
+3. **Verification checklist** — How to prove this phase worked (tests, grep checks)
+4. **Anti-pattern guards** — What NOT to do (invented APIs, undocumented params)
+
+### Final Phase: Verification
+
+1. Verify all implementations match documentation
+2. Check for anti-patterns (grep for known bad patterns)
+3. Run tests to confirm functionality
+
+## Key Principles
+
+- Documentation Availability ≠ Usage: Explicitly require reading docs
+- Task Framing Matters: Direct agents to docs, not just outcomes
+- Verify > Assume: Require proof, not assumptions about APIs
+- Session Boundaries: Each phase should be self-contained with its own doc references
+
+## Anti-Patterns to Prevent
+
+- Inventing API methods that "should" exist
+- Adding parameters not in documentation
+- Skipping verification steps
+- Assuming structure without checking examples

plugin/skills/mem-search/SKILL.md

@@ -93,20 +93,6 @@ get_observations(ids=[11131, 10942])
 
 **Returns:** Complete observation objects with title, subtitle, narrative, facts, concepts, files (~500-1000 tokens each)
 
-## Saving Memories
-
-Use the `save_memory` MCP tool to store manual observations:
-
-```
-save_memory(text="Important discovery about the auth system", title="Auth Architecture", project="my-project")
-```
-
-**Parameters:**
-
-- `text` (string, required) - Content to remember
-- `title` (string, optional) - Short title, auto-generated if omitted
-- `project` (string, optional) - Project name, defaults to "claude-mem"
-
 ## Examples
 
 **Find recent bug fixes:**

plugin/skills/smart-explore/SKILL.md

@@ -0,0 +1,145 @@
+---
+name: smart-explore
+description: Token-optimized structural code search using tree-sitter AST parsing. Use instead of reading full files when you need to understand code structure, find functions, or explore a codebase efficiently.
+---
+
+# Smart Explore
+
+Structural code exploration using AST parsing. **This skill overrides your default exploration behavior.** While this skill is active, use smart_search/smart_outline/smart_unfold as your primary tools instead of Read, Grep, and Glob.
+
+**Core principle:** Index first, fetch on demand. Give yourself a map of the code before loading implementation details. The question before every file read should be: "do I need to see all of this, or can I get a structural overview first?" The answer is almost always: get the map.
+
+## Your Next Tool Call
+
+This skill only loads instructions. You must call the MCP tools yourself. Your next action should be one of:
+
+```
+smart_search(query="<topic>", path="./src")    -- discover files + symbols across a directory
+smart_outline(file_path="<file>")              -- structural skeleton of one file
+smart_unfold(file_path="<file>", symbol_name="<name>")  -- full source of one symbol
+```
+
+Do NOT run Grep, Glob, Read, or find to discover files first. `smart_search` walks directories, parses all code files, and returns ranked symbols in one call. It replaces the Glob → Grep → Read discovery cycle.
+
+## 3-Layer Workflow
+
+### Step 1: Search -- Discover Files and Symbols
+
+```
+smart_search(query="shutdown", path="./src", max_results=15)
+```
+
+**Returns:** Ranked symbols with signatures, line numbers, match reasons, plus folded file views (~2-6k tokens)
+
+```
+-- Matching Symbols --
+  function performGracefulShutdown (services/infrastructure/GracefulShutdown.ts:56)
+  function httpShutdown (services/infrastructure/HealthMonitor.ts:92)
+  method WorkerService.shutdown (services/worker-service.ts:846)
+
+-- Folded File Views --
+  services/infrastructure/GracefulShutdown.ts (7 symbols)
+  services/worker-service.ts (12 symbols)
+```
+
+This is your discovery tool. It finds relevant files AND shows their structure. No Glob/find pre-scan needed.
+
+**Parameters:**
+
+- `query` (string, required) -- What to search for (function name, concept, class name)
+- `path` (string) -- Root directory to search (defaults to cwd)
+- `max_results` (number) -- Max matching symbols, default 20, max 50
+- `file_pattern` (string, optional) -- Filter to specific files/paths
+
+### Step 2: Outline -- Get File Structure
+
+```
+smart_outline(file_path="services/worker-service.ts")
+```
+
+**Returns:** Complete structural skeleton -- all functions, classes, methods, properties, imports (~1-2k tokens per file)
+
+**Skip this step** when Step 1's folded file views already provide enough structure. Most useful for files not covered by the search results.
+
+**Parameters:**
+
+- `file_path` (string, required) -- Path to the file
+
+### Step 3: Unfold -- See Implementation
+
+Review symbols from Steps 1-2. Pick the ones you need. Unfold only those:
+
+```
+smart_unfold(file_path="services/worker-service.ts", symbol_name="shutdown")
+```
+
+**Returns:** Full source code of the specified symbol including JSDoc, decorators, and complete implementation (~400-2,100 tokens depending on symbol size). AST node boundaries guarantee completeness regardless of symbol size — unlike Read + agent summarization, which may truncate long methods.
+
+**Parameters:**
+
+- `file_path` (string, required) -- Path to the file (as returned by search/outline)
+- `symbol_name` (string, required) -- Name of the function/class/method to expand
+
+## When to Use Standard Tools Instead
+
+Use these only when smart_* tools are the wrong fit:
+
+- **Grep:** Exact string/regex search ("find all TODO comments", "where is `ensureWorkerStarted` defined?")
+- **Read:** Small files under ~100 lines, non-code files (JSON, markdown, config)
+- **Glob:** File path patterns ("find all test files")
+- **Explore agent:** When you need synthesized understanding across 6+ files, architecture narratives, or answers to open-ended questions like "how does this entire system work end-to-end?" Smart-explore is a scalpel — it answers "where is this?" and "show me that." It doesn't synthesize cross-file data flows, design decisions, or edge cases across an entire feature.
+
+For code files over ~100 lines, prefer smart_outline + smart_unfold over Read.
+
+## Workflow Examples
+
+**Discover how a feature works (cross-cutting):**
+
+```
+1. smart_search(query="shutdown", path="./src")
+   -> 14 symbols across 7 files, full picture in one call
+2. smart_unfold(file_path="services/infrastructure/GracefulShutdown.ts", symbol_name="performGracefulShutdown")
+   -> See the core implementation
+```
+
+**Navigate a large file:**
+
+```
+1. smart_outline(file_path="services/worker-service.ts")
+   -> 1,466 tokens: 12 functions, WorkerService class with 24 members
+2. smart_unfold(file_path="services/worker-service.ts", symbol_name="startSessionProcessor")
+   -> 1,610 tokens: the specific method you need
+Total: ~3,076 tokens vs ~12,000 to Read the full file
+```
+
+**Write documentation about code (hybrid workflow):**
+
+```
+1. smart_search(query="feature name", path="./src")    -- discover all relevant files and symbols
+2. smart_outline on key files                           -- understand structure
+3. smart_unfold on important functions                  -- get implementation details
+4. Read on small config/markdown/plan files             -- get non-code context
+```
+
+Use smart_* tools for code exploration, Read for non-code files. Mix freely.
+
+**Exploration then precision:**
+
+```
+1. smart_search(query="session", path="./src", max_results=10)
+   -> 10 ranked symbols: SessionMetadata, SessionQueueProcessor, SessionSummary...
+2. Pick the relevant one, unfold it
+```
+
+## Token Economics
+
+| Approach | Tokens | Use Case |
+|----------|--------|----------|
+| smart_outline | ~1,000-2,000 | "What's in this file?" |
+| smart_unfold | ~400-2,100 | "Show me this function" |
+| smart_search | ~2,000-6,000 | "Find all X across the codebase" |
+| search + unfold | ~3,000-8,000 | End-to-end: find and read (the primary workflow) |
+| Read (full file) | ~12,000+ | When you truly need everything |
+| Explore agent | ~39,000-59,000 | Cross-file synthesis with narrative |
+
+**4-8x savings** on file understanding (outline + unfold vs Read). **11-18x savings** on codebase exploration vs Explore agent. The narrower the query, the wider the gap — a 27-line function costs 55x less to read via unfold than via an Explore agent, because the agent still reads the entire file.

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

@@ -0,0 +1 @@
+Never read built source files in this directory. These are compiled outputs — read the source files in `src/` instead.

scripts/build-hooks.js

@@ -59,8 +59,16 @@ async function buildHooks() {
       description: 'Runtime dependencies for claude-mem bundled hooks',
       type: 'module',
       dependencies: {
-        // Chroma embedding function with native ONNX binaries (can't be bundled)
-        '@chroma-core/default-embed': '^0.1.9'
+        'tree-sitter-cli': '^0.26.5',
+        'tree-sitter-c': '^0.24.1',
+        'tree-sitter-cpp': '^0.23.4',
+        'tree-sitter-go': '^0.25.0',
+        'tree-sitter-java': '^0.23.5',
+        'tree-sitter-javascript': '^0.25.0',
+        'tree-sitter-python': '^0.25.0',
+        'tree-sitter-ruby': '^0.23.1',
+        'tree-sitter-rust': '^0.24.0',
+        'tree-sitter-typescript': '^0.23.2',
       },
       engines: {
         node: '>=18.0.0',
@@ -108,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')
       }
     });
 
@@ -128,7 +140,19 @@ async function buildHooks() {
       outfile: `${hooksDir}/${MCP_SERVER.name}.cjs`,
       minify: true,
       logLevel: 'error',
-      external: ['bun:sqlite'],
+      external: [
+        'bun:sqlite',
+        'tree-sitter-cli',
+        'tree-sitter-javascript',
+        'tree-sitter-typescript',
+        'tree-sitter-python',
+        'tree-sitter-go',
+        'tree-sitter-rust',
+        'tree-sitter-ruby',
+        'tree-sitter-java',
+        'tree-sitter-c',
+        'tree-sitter-cpp',
+      ],
       define: {
         '__DEFAULT_PACKAGE_VERSION__': `"${version}"`
       },
@@ -156,17 +180,126 @@ 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)`);
 
-    console.log('\n✅ Worker service, MCP server, and context generator built successfully!');
+    // 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 = [
+      'plugin/skills/mem-search/SKILL.md',
+      'plugin/skills/smart-explore/SKILL.md',
+      'plugin/hooks/hooks.json',
+      'plugin/.claude-plugin/plugin.json',
+    ];
+    for (const filePath of requiredDistributionFiles) {
+      if (!fs.existsSync(filePath)) {
+        throw new Error(`Missing required distribution file: ${filePath}`);
+      }
+    }
+    console.log('✓ All required distribution files present');
+
+    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

scripts/regenerate-claude-md.ts

@@ -279,6 +279,11 @@ function formatObservationsForClaudeMd(observations: ObservationRow[], folderPat
  * which only writes to existing folders.
  */
 function writeClaudeMdToFolderForRegenerate(folderPath: string, newContent: string): void {
+  const resolvedPath = path.resolve(folderPath);
+
+  // Never write inside .git directories — corrupts refs (#1165)
+  if (resolvedPath.includes('/.git/') || resolvedPath.includes('\\.git\\') || resolvedPath.endsWith('/.git') || resolvedPath.endsWith('\\.git')) return;
+
   const claudeMdPath = path.join(folderPath, 'CLAUDE.md');
   const tempFile = `${claudeMdPath}.tmp`;
 

scripts/smart-install.js

@@ -5,36 +5,42 @@
  * Ensures Bun runtime and uv (Python package manager) are installed
  * (auto-installs if missing) and handles dependency installation when needed.
  */
-import { existsSync, readFileSync, writeFileSync, rmSync } from 'fs';
+import { existsSync, readFileSync, writeFileSync } from 'fs';
 import { execSync, spawnSync } from 'child_process';
-import { join } from 'path';
+import { join, dirname } from 'path';
 import { homedir } from 'os';
+import { fileURLToPath } from 'url';
 
 const IS_WINDOWS = process.platform === 'win32';
 
 /**
- * Resolve the marketplace root directory.
+ * Resolve the plugin root directory where dependencies should be installed.
  *
- * Claude Code may store plugins under either `~/.claude/plugins/` (legacy) or
- * `~/.config/claude/plugins/` (XDG-compliant, e.g. Nix-managed installs).
- * When `CLAUDE_PLUGIN_ROOT` is set we derive the base from it; otherwise we
- * probe both candidate paths and fall back to the legacy location.
+ * Priority:
+ * 1. CLAUDE_PLUGIN_ROOT env var (set by Claude Code for hooks — works for
+ *    both cache-based and marketplace installs)
+ * 2. Script location (dirname of this file, up one level from scripts/)
+ * 3. XDG path (~/.config/claude/plugins/marketplaces/thedotmack)
+ * 4. Legacy path (~/.claude/plugins/marketplaces/thedotmack)
  */
 function resolveRoot() {
-  const marketplaceRel = join('plugins', 'marketplaces', 'thedotmack');
-
-  // Derive from CLAUDE_PLUGIN_ROOT (e.g. .../plugins/cache/thedotmack/claude-mem/<ver>)
+  // CLAUDE_PLUGIN_ROOT is the authoritative location set by Claude Code
   if (process.env.CLAUDE_PLUGIN_ROOT) {
-    let dir = process.env.CLAUDE_PLUGIN_ROOT;
-    const cacheIndex = dir.indexOf(join('plugins', 'cache'));
-    if (cacheIndex !== -1) {
-      const base = dir.substring(0, cacheIndex);
-      const candidate = join(base, marketplaceRel);
-      if (existsSync(join(candidate, 'package.json'))) return candidate;
-    }
+    const root = process.env.CLAUDE_PLUGIN_ROOT;
+    if (existsSync(join(root, 'package.json'))) return root;
   }
 
-  // Probe XDG path first, then legacy
+  // Derive from script location (this file is in <root>/scripts/)
+  try {
+    const scriptDir = dirname(fileURLToPath(import.meta.url));
+    const candidate = dirname(scriptDir);
+    if (existsSync(join(candidate, 'package.json'))) return candidate;
+  } catch {
+    // import.meta.url not available
+  }
+
+  // Probe XDG path, then legacy
+  const marketplaceRel = join('plugins', 'marketplaces', 'thedotmack');
   const xdg = join(homedir(), '.config', 'claude', marketplaceRel);
   if (existsSync(join(xdg, 'package.json'))) return xdg;
 
@@ -260,15 +266,6 @@ function installDeps() {
 
   console.error('📦 Installing dependencies with Bun...');
 
-  // Clear stale native module cache (sharp/libvips) to prevent broken dylib references.
-  // Bun's cache can retain native binaries that reference companion libraries at
-  // broken relative paths after version upgrades.
-  const bunCacheImgDir = join(homedir(), '.bun', 'install', 'cache', '@img');
-  if (existsSync(bunCacheImgDir)) {
-    console.error('   Clearing stale native module cache (@img/sharp)...');
-    rmSync(bunCacheImgDir, { recursive: true, force: true });
-  }
-
   // Quote path for Windows paths with spaces
   const bunCmd = IS_WINDOWS && bunPath.includes(' ') ? `"${bunPath}"` : bunPath;
 
@@ -284,12 +281,42 @@ function installDeps() {
   }));
 }
 
+/**
+ * Verify that critical runtime modules are resolvable from the install directory.
+ * Returns true if all critical modules exist, false otherwise.
+ */
+function verifyCriticalModules() {
+  const pkg = JSON.parse(readFileSync(join(ROOT, 'package.json'), 'utf-8'));
+  const dependencies = Object.keys(pkg.dependencies || {});
+
+  const missing = [];
+  for (const dep of dependencies) {
+    const modulePath = join(ROOT, 'node_modules', ...dep.split('/'));
+    if (!existsSync(modulePath)) {
+      missing.push(dep);
+    }
+  }
+
+  if (missing.length > 0) {
+    console.error(`❌ Post-install check failed: missing modules: ${missing.join(', ')}`);
+    return false;
+  }
+
+  return true;
+}
+
 // Main execution
 try {
   if (!isBunInstalled()) installBun();
   if (!isUvInstalled()) installUv();
   if (needsInstall()) {
     installDeps();
+
+    if (!verifyCriticalModules()) {
+      console.error('❌ Dependencies could not be installed. Plugin may not work correctly.');
+      process.exit(1);
+    }
+
     console.error('✅ Dependencies installed');
   }
 } catch (e) {

scripts/sync-marketplace.cjs

@@ -76,28 +76,10 @@ try {
   const gitignoreExcludes = getGitignoreExcludes(rootDir);
 
   execSync(
-    `rsync -av --delete --exclude=.git --exclude=/.mcp.json --exclude=bun.lock --exclude=package-lock.json ${gitignoreExcludes} ./ ~/.claude/plugins/marketplaces/thedotmack/`,
+    `rsync -av --delete --exclude=.git --exclude=bun.lock --exclude=package-lock.json ${gitignoreExcludes} ./ ~/.claude/plugins/marketplaces/thedotmack/`,
     { stdio: 'inherit' }
   );
 
-  // Remove stale lockfiles before install — they pin old native dep versions
-  const { unlinkSync, rmSync } = require('fs');
-  for (const lockfile of ['package-lock.json', 'bun.lock']) {
-    const lockpath = path.join(INSTALLED_PATH, lockfile);
-    if (existsSync(lockpath)) {
-      unlinkSync(lockpath);
-      console.log(`Removed stale ${lockfile}`);
-    }
-  }
-
-  // Clear stale native module cache (sharp/libvips) — Bun's cache can retain
-  // native binaries that reference companion libraries at broken relative paths
-  const bunCacheImgDir = path.join(os.homedir(), '.bun', 'install', 'cache', '@img');
-  if (existsSync(bunCacheImgDir)) {
-    rmSync(bunCacheImgDir, { recursive: true, force: true });
-    console.log('Cleared stale native module cache (@img/sharp)');
-  }
-
   console.log('Running bun install in marketplace...');
   execSync(
     'cd ~/.claude/plugins/marketplaces/thedotmack/ && bun install',
@@ -117,6 +99,10 @@ try {
     { stdio: 'inherit' }
   );
 
+  // Install dependencies in cache directory so worker can resolve them
+  console.log(`Running bun install in cache folder (version ${version})...`);
+  execSync(`bun install`, { cwd: CACHE_VERSION_PATH, stdio: 'inherit' });
+
   console.log('\x1b[32m%s\x1b[0m', 'Sync complete!');
 
   // Trigger worker restart after file sync

scripts/wipe-chroma.cjs

@@ -0,0 +1,19 @@
+#!/usr/bin/env node
+/**
+ * Wipes the Chroma data directory so backfillAllProjects rebuilds it on next worker start.
+ * Chroma is always rebuildable from SQLite — this is safe.
+ */
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+
+const chromaDir = path.join(os.homedir(), '.claude-mem', 'chroma');
+
+if (fs.existsSync(chromaDir)) {
+  const before = fs.readdirSync(chromaDir);
+  console.log(`Wiping ${chromaDir} (${before.length} items)...`);
+  fs.rmSync(chromaDir, { recursive: true, force: true });
+  console.log('Done. Chroma will rebuild from SQLite on next worker restart.');
+} else {
+  console.log('Chroma directory does not exist, nothing to wipe.');
+}

src/cli/adapters/claude-code.ts

@@ -6,7 +6,7 @@ export const claudeCodeAdapter: PlatformAdapter = {
   normalizeInput(raw) {
     const r = (raw ?? {}) as any;
     return {
-      sessionId: r.session_id,
+      sessionId: r.session_id ?? r.id ?? r.sessionId,
       cwd: r.cwd ?? process.cwd(),
       prompt: r.prompt,
       toolName: r.tool_name,
@@ -16,13 +16,20 @@ export const claudeCodeAdapter: PlatformAdapter = {
     };
   },
   formatOutput(result) {
-    if (result.hookSpecificOutput) {
+    const r = result ?? ({} as HookResult);
+    if (r.hookSpecificOutput) {
       const output: Record<string, unknown> = { hookSpecificOutput: result.hookSpecificOutput };
-      if (result.systemMessage) {
-        output.systemMessage = result.systemMessage;
+      if (r.systemMessage) {
+        output.systemMessage = r.systemMessage;
       }
       return output;
     }
-    return { continue: result.continue ?? true, suppressOutput: result.suppressOutput ?? true };
+    // Only emit fields in the Claude Code hook contract — unrecognized fields
+    // cause "JSON validation failed" in Stop hooks.
+    const output: Record<string, unknown> = {};
+    if (r.systemMessage) {
+      output.systemMessage = r.systemMessage;
+    }
+    return output;
   }
 };

src/cli/adapters/cursor.ts

@@ -3,15 +3,20 @@ import type { PlatformAdapter, NormalizedHookInput, HookResult } from '../types.
 // Maps Cursor stdin format - field names differ from Claude Code
 // Cursor uses: conversation_id, workspace_roots[], result_json, command/output
 // Handle undefined input gracefully for hooks that don't receive stdin
+//
+// Cursor payload variations (#838, #1049):
+//   Session ID: conversation_id, generation_id, or id
+//   Prompt: prompt, query, input, or message (varies by Cursor version/hook type)
+//   CWD: workspace_roots[0] or cwd
 export const cursorAdapter: PlatformAdapter = {
   normalizeInput(raw) {
     const r = (raw ?? {}) as any;
     // Cursor-specific: shell commands come as command/output instead of tool_name/input/response
     const isShellCommand = !!r.command && !r.tool_name;
     return {
-      sessionId: r.conversation_id || r.generation_id,  // conversation_id preferred
-      cwd: r.workspace_roots?.[0] ?? process.cwd(),     // First workspace root
-      prompt: r.prompt,
+      sessionId: r.conversation_id || r.generation_id || r.id,
+      cwd: r.workspace_roots?.[0] ?? r.cwd ?? process.cwd(),
+      prompt: r.prompt ?? r.query ?? r.input ?? r.message,
       toolName: isShellCommand ? 'Bash' : r.tool_name,
       toolInput: isShellCommand ? { command: r.command } : r.tool_input,
       toolResponse: isShellCommand ? { output: r.output } : r.result_json,  // result_json not tool_response

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,15 +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;
-    default: throw new Error(`Unknown platform: ${platform}`);
+    // 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/claude-md-commands.ts

@@ -264,6 +264,11 @@ function formatObservationsForClaudeMd(observations: ObservationRow[], folderPat
  * Only writes to folders that exist — never creates directories.
  */
 function writeClaudeMdToFolder(folderPath: string, newContent: string): void {
+  const resolvedPath = path.resolve(folderPath);
+
+  // Never write inside .git directories — corrupts refs (#1165)
+  if (resolvedPath.includes('/.git/') || resolvedPath.includes('\\.git\\') || resolvedPath.endsWith('/.git') || resolvedPath.endsWith('\\.git')) return;
+
   const claudeMdPath = path.join(folderPath, 'CLAUDE.md');
   const tempFile = `${claudeMdPath}.tmp`;
 

src/cli/handlers/context.ts

@@ -6,10 +6,12 @@
  */
 
 import type { EventHandler, NormalizedHookInput, HookResult } from '../types.js';
-import { ensureWorkerRunning, getWorkerPort } from '../../shared/worker-utils.js';
+import { ensureWorkerRunning, getWorkerPort, workerHttpRequest } from '../../shared/worker-utils.js';
 import { getProjectContext } from '../../utils/project-name.js';
 import { HOOK_EXIT_CODES } from '../../shared/hook-constants.js';
 import { logger } from '../../utils/logger.js';
+import { SettingsDefaultsManager } from '../../shared/SettingsDefaultsManager.js';
+import { USER_SETTINGS_PATH } from '../../shared/paths.js';
 
 export const contextHandler: EventHandler = {
   async execute(input: NormalizedHookInput): Promise<HookResult> {
@@ -30,18 +32,22 @@ export const contextHandler: EventHandler = {
     const context = getProjectContext(cwd);
     const port = getWorkerPort();
 
+    // Check if terminal output should be shown (load settings early)
+    const settings = SettingsDefaultsManager.loadFromFile(USER_SETTINGS_PATH);
+    const showTerminalOutput = settings.CLAUDE_MEM_CONTEXT_SHOW_TERMINAL_OUTPUT === 'true';
+
     // Pass all projects (parent + worktree if applicable) for unified timeline
     const projectsParam = context.allProjects.join(',');
-    const url = `http://127.0.0.1:${port}/api/context/inject?projects=${encodeURIComponent(projectsParam)}`;
+    const apiPath = `/api/context/inject?projects=${encodeURIComponent(projectsParam)}`;
+    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
     try {
-      // Fetch both markdown (for Claude context) and colored (for user display) truly in parallel
-      const colorUrl = `${url}&colors=true`;
+      // Fetch markdown (for Claude context) and optionally colored (for user display)
       const [response, colorResponse] = await Promise.all([
-        fetch(url),
-        fetch(colorUrl).catch(() => null)
+        workerHttpRequest(apiPath),
+        showTerminalOutput ? workerHttpRequest(colorApiPath).catch(() => null) : Promise.resolve(null)
       ]);
 
       if (!response.ok) {
@@ -60,8 +66,15 @@ export const contextHandler: EventHandler = {
 
       const additionalContext = contextResult.trim();
       const coloredTimeline = colorResult.trim();
-      const systemMessage = coloredTimeline
-        ? `${coloredTimeline}\n\nView Observations Live @ http://localhost:${port}`
+      const platform = input.platform;
+
+      // 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/file-edit.ts

@@ -6,7 +6,7 @@
  */
 
 import type { EventHandler, NormalizedHookInput, HookResult } from '../types.js';
-import { ensureWorkerRunning, getWorkerPort } from '../../shared/worker-utils.js';
+import { ensureWorkerRunning, workerHttpRequest } from '../../shared/worker-utils.js';
 import { logger } from '../../utils/logger.js';
 import { HOOK_EXIT_CODES } from '../../shared/hook-constants.js';
 
@@ -25,10 +25,7 @@ export const fileEditHandler: EventHandler = {
       throw new Error('fileEditHandler requires filePath');
     }
 
-    const port = getWorkerPort();
-
     logger.dataIn('HOOK', `FileEdit: ${filePath}`, {
-      workerPort: port,
       editCount: edits?.length ?? 0
     });
 
@@ -40,7 +37,7 @@ export const fileEditHandler: EventHandler = {
     // Send to worker as an observation with file edit metadata
     // The observation handler on the worker will process this appropriately
     try {
-      const response = await fetch(`http://127.0.0.1:${port}/api/sessions/observations`, {
+      const response = await workerHttpRequest('/api/sessions/observations', {
         method: 'POST',
         headers: { 'Content-Type': 'application/json' },
         body: JSON.stringify({
@@ -50,7 +47,6 @@ export const fileEditHandler: EventHandler = {
           tool_response: { success: true },
           cwd
         })
-        // Note: Removed signal to avoid Windows Bun cleanup issue (libuv assertion)
       });
 
       if (!response.ok) {

src/cli/handlers/index.ts

@@ -6,6 +6,7 @@
 
 import type { EventHandler } from '../types.js';
 import { HOOK_EXIT_CODES } from '../../shared/hook-constants.js';
+import { logger } from '../../utils/logger.js';
 import { contextHandler } from './context.js';
 import { sessionInitHandler } from './session-init.js';
 import { observationHandler } from './observation.js';
@@ -46,7 +47,7 @@ const handlers: Record<EventType, EventHandler> = {
 export function getEventHandler(eventType: string): EventHandler {
   const handler = handlers[eventType as EventType];
   if (!handler) {
-    console.error(`[claude-mem] Unknown event type: ${eventType}, returning no-op`);
+    logger.warn('HOOK', `Unknown event type: ${eventType}, returning no-op`);
     return {
       async execute() {
         return { continue: true, suppressOutput: true, exitCode: HOOK_EXIT_CODES.SUCCESS };

src/cli/handlers/observation.ts

@@ -5,7 +5,7 @@
  */
 
 import type { EventHandler, NormalizedHookInput, HookResult } from '../types.js';
-import { ensureWorkerRunning, getWorkerPort } from '../../shared/worker-utils.js';
+import { ensureWorkerRunning, workerHttpRequest } from '../../shared/worker-utils.js';
 import { logger } from '../../utils/logger.js';
 import { HOOK_EXIT_CODES } from '../../shared/hook-constants.js';
 import { isProjectExcluded } from '../../utils/project-filter.js';
@@ -28,13 +28,9 @@ export const observationHandler: EventHandler = {
       return { continue: true, suppressOutput: true, exitCode: HOOK_EXIT_CODES.SUCCESS };
     }
 
-    const port = getWorkerPort();
-
     const toolStr = logger.formatTool(toolName, toolInput);
 
-    logger.dataIn('HOOK', `PostToolUse: ${toolStr}`, {
-      workerPort: port
-    });
+    logger.dataIn('HOOK', `PostToolUse: ${toolStr}`, {});
 
     // Validate required fields before sending to worker
     if (!cwd) {
@@ -50,7 +46,7 @@ export const observationHandler: EventHandler = {
 
     // Send to worker - worker handles privacy check and database operations
     try {
-      const response = await fetch(`http://127.0.0.1:${port}/api/sessions/observations`, {
+      const response = await workerHttpRequest('/api/sessions/observations', {
         method: 'POST',
         headers: { 'Content-Type': 'application/json' },
         body: JSON.stringify({
@@ -60,7 +56,6 @@ export const observationHandler: EventHandler = {
           tool_response: toolResponse,
           cwd
         })
-        // Note: Removed signal to avoid Windows Bun cleanup issue (libuv assertion)
       });
 
       if (!response.ok) {

src/cli/handlers/session-complete.ts

@@ -10,7 +10,7 @@
  */
 
 import type { EventHandler, NormalizedHookInput, HookResult } from '../types.js';
-import { ensureWorkerRunning, getWorkerPort } from '../../shared/worker-utils.js';
+import { ensureWorkerRunning, workerHttpRequest } from '../../shared/worker-utils.js';
 import { logger } from '../../utils/logger.js';
 
 export const sessionCompleteHandler: EventHandler = {
@@ -23,7 +23,6 @@ export const sessionCompleteHandler: EventHandler = {
     }
 
     const { sessionId } = input;
-    const port = getWorkerPort();
 
     if (!sessionId) {
       logger.warn('HOOK', 'session-complete: Missing sessionId, skipping');
@@ -31,13 +30,12 @@ export const sessionCompleteHandler: EventHandler = {
     }
 
     logger.info('HOOK', '→ session-complete: Removing session from active map', {
-      workerPort: port,
       contentSessionId: sessionId
     });
 
     try {
       // Call the session complete endpoint by contentSessionId
-      const response = await fetch(`http://127.0.0.1:${port}/api/sessions/complete`, {
+      const response = await workerHttpRequest('/api/sessions/complete', {
         method: 'POST',
         headers: { 'Content-Type': 'application/json' },
         body: JSON.stringify({

src/cli/handlers/session-init.ts

@@ -5,7 +5,7 @@
  */
 
 import type { EventHandler, NormalizedHookInput, HookResult } from '../types.js';
-import { ensureWorkerRunning, getWorkerPort } from '../../shared/worker-utils.js';
+import { ensureWorkerRunning, workerHttpRequest } from '../../shared/worker-utils.js';
 import { getProjectName } from '../../utils/project-name.js';
 import { logger } from '../../utils/logger.js';
 import { HOOK_EXIT_CODES } from '../../shared/hook-constants.js';
@@ -24,6 +24,12 @@ export const sessionInitHandler: EventHandler = {
 
     const { sessionId, cwd, prompt: rawPrompt } = input;
 
+    // Guard: Codex CLI and other platforms may not provide a session_id (#744)
+    if (!sessionId) {
+      logger.warn('HOOK', 'session-init: No sessionId provided, skipping (Codex CLI or unknown platform)');
+      return { continue: true, suppressOutput: true, exitCode: HOOK_EXIT_CODES.SUCCESS };
+    }
+
     // Check if project is excluded from tracking
     const settings = SettingsDefaultsManager.loadFromFile(USER_SETTINGS_PATH);
     if (cwd && isProjectExcluded(cwd, settings.CLAUDE_MEM_EXCLUDED_PROJECTS)) {
@@ -36,12 +42,11 @@ export const sessionInitHandler: EventHandler = {
     const prompt = (!rawPrompt || !rawPrompt.trim()) ? '[media prompt]' : rawPrompt;
 
     const project = getProjectName(cwd);
-    const port = getWorkerPort();
 
     logger.debug('HOOK', 'session-init: Calling /api/sessions/init', { contentSessionId: sessionId, project });
 
     // Initialize session via HTTP - handles DB operations and privacy checks
-    const initResponse = await fetch(`http://127.0.0.1:${port}/api/sessions/init`, {
+    const initResponse = await workerHttpRequest('/api/sessions/init', {
       method: 'POST',
       headers: { 'Content-Type': 'application/json' },
       body: JSON.stringify({
@@ -49,7 +54,6 @@ export const sessionInitHandler: EventHandler = {
         project,
         prompt
       })
-      // Note: Removed signal to avoid Windows Bun cleanup issue (libuv assertion)
     });
 
     if (!initResponse.ok) {
@@ -63,11 +67,12 @@ export const sessionInitHandler: EventHandler = {
       promptNumber: number;
       skipped?: boolean;
       reason?: string;
+      contextInjected?: boolean;
     };
     const sessionDbId = initResult.sessionDbId;
     const promptNumber = initResult.promptNumber;
 
-    logger.debug('HOOK', 'session-init: Received from /api/sessions/init', { sessionDbId, promptNumber, skipped: initResult.skipped });
+    logger.debug('HOOK', 'session-init: Received from /api/sessions/init', { sessionDbId, promptNumber, skipped: initResult.skipped, contextInjected: initResult.contextInjected });
 
     // Debug-level alignment log for detailed tracing
     logger.debug('HOOK', `[ALIGNMENT] Hook Entry | contentSessionId=${sessionId} | prompt#=${promptNumber} | sessionDbId=${sessionDbId}`);
@@ -80,9 +85,20 @@ export const sessionInitHandler: EventHandler = {
       return { continue: true, suppressOutput: true };
     }
 
+    // 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.
+    // 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
+      });
+    }
+
     // 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;
@@ -90,25 +106,68 @@ export const sessionInitHandler: EventHandler = {
       logger.debug('HOOK', 'session-init: Calling /sessions/{sessionDbId}/init', { sessionDbId, promptNumber });
 
       // Initialize SDK agent session via HTTP (starts the agent!)
-      const response = await fetch(`http://127.0.0.1:${port}/sessions/${sessionDbId}/init`, {
+      const response = await workerHttpRequest(`/sessions/${sessionDbId}/init`, {
         method: 'POST',
         headers: { 'Content-Type': 'application/json' },
         body: JSON.stringify({ userPrompt: cleanedPrompt, promptNumber })
-        // Note: Removed signal to avoid Windows Bun cleanup issue (libuv assertion)
       });
 
       if (!response.ok) {
         // 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,18 +1,27 @@
 /**
  * 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';
-import { ensureWorkerRunning, getWorkerPort, fetchWithTimeout } from '../../shared/worker-utils.js';
+import { ensureWorkerRunning, workerHttpRequest } from '../../shared/worker-utils.js';
 import { logger } from '../../utils/logger.js';
 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> {
@@ -25,8 +34,6 @@ export const summarizeHandler: EventHandler = {
 
     const { sessionId, transcriptPath } = input;
 
-    const port = getWorkerPort();
-
     // Validate required fields before processing
     if (!transcriptPath) {
       // No transcript available - skip summary gracefully (not an error)
@@ -37,33 +44,83 @@ 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', {
-      workerPort: port,
       hasLastAssistantMessage: !!lastAssistantMessage
     });
 
-    // Send to worker - worker handles privacy check and database operations
-    const response = await fetchWithTimeout(
-      `http://127.0.0.1:${port}/api/sessions/summarize`,
-      {
-        method: 'POST',
-        headers: { 'Content-Type': 'application/json' },
-        body: JSON.stringify({
-          contentSessionId: sessionId,
-          last_assistant_message: lastAssistantMessage
-        }),
-      },
-      SUMMARIZE_TIMEOUT_MS
-    );
+    // 1. Queue summarize request — worker returns immediately with { status: 'queued' }
+    const response = await workerHttpRequest('/api/sessions/summarize', {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({
+        contentSessionId: sessionId,
+        last_assistant_message: lastAssistantMessage
+      }),
+      timeoutMs: SUMMARIZE_TIMEOUT_MS
+    });
 
     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

@@ -7,7 +7,7 @@
 
 import { basename } from 'path';
 import type { EventHandler, NormalizedHookInput, HookResult } from '../types.js';
-import { ensureWorkerRunning, getWorkerPort } from '../../shared/worker-utils.js';
+import { ensureWorkerRunning, getWorkerPort, workerHttpRequest } from '../../shared/worker-utils.js';
 import { HOOK_EXIT_CODES } from '../../shared/hook-constants.js';
 
 export const userMessageHandler: EventHandler = {
@@ -23,11 +23,11 @@ export const userMessageHandler: EventHandler = {
     const project = basename(input.cwd ?? process.cwd());
 
     // Fetch formatted context directly from worker API
-    // Note: Removed AbortSignal.timeout to avoid Windows Bun cleanup issue (libuv assertion)
+    // Only request ANSI colors for platforms that render them (claude-code)
+    const colorsParam = input.platform === 'claude-code' ? '&colors=true' : '';
     try {
-      const response = await fetch(
-        `http://127.0.0.1:${port}/api/context/inject?project=${encodeURIComponent(project)}&colors=true`,
-        { method: 'GET' }
+      const response = await workerHttpRequest(
+        `/api/context/inject?project=${encodeURIComponent(project)}${colorsParam}`
       );
 
       if (!response.ok) {

src/cli/hook-command.ts

@@ -2,6 +2,7 @@ import { readJsonFromStdin } from './stdin-reader.js';
 import { getPlatformAdapter } from './adapters/index.js';
 import { getEventHandler } from './handlers/index.js';
 import { HOOK_EXIT_CODES } from '../shared/hook-constants.js';
+import { logger } from '../utils/logger.js';
 
 export interface HookCommandOptions {
   /** If true, don't call process.exit() - let caller handle process lifecycle */
@@ -65,6 +66,12 @@ export function isWorkerUnavailableError(error: unknown): boolean {
 }
 
 export async function hookCommand(platform: string, event: string, options: HookCommandOptions = {}): Promise<number> {
+  // Suppress stderr in hook context — Claude Code shows stderr as error UI (#1181)
+  // Exit 1: stderr shown to user. Exit 2: stderr fed to Claude for processing.
+  // All diagnostics go to log file via logger; stderr must stay clean.
+  const originalStderrWrite = process.stderr.write.bind(process.stderr);
+  process.stderr.write = (() => true) as typeof process.stderr.write;
+
   try {
     const adapter = getPlatformAdapter(platform);
     const handler = getEventHandler(event);
@@ -84,18 +91,22 @@ export async function hookCommand(platform: string, event: string, options: Hook
   } catch (error) {
     if (isWorkerUnavailableError(error)) {
       // Worker unavailable — degrade gracefully, don't block the user
-      console.error(`[claude-mem] Worker unavailable, skipping hook: ${error instanceof Error ? error.message : error}`);
+      // Log to file instead of stderr (#1181)
+      logger.warn('HOOK', `Worker unavailable, skipping hook: ${error instanceof Error ? error.message : error}`);
       if (!options.skipExit) {
         process.exit(HOOK_EXIT_CODES.SUCCESS);  // = 0 (graceful)
       }
       return HOOK_EXIT_CODES.SUCCESS;
     }
 
-    // Handler/client bug — show as blocking error so developers see it
-    console.error(`Hook error: ${error}`);
+    // Handler/client bug — log to file instead of stderr (#1181)
+    logger.error('HOOK', `Hook error: ${error instanceof Error ? error.message : error}`, {}, error instanceof Error ? error : undefined);
     if (!options.skipExit) {
       process.exit(HOOK_EXIT_CODES.BLOCKING_ERROR);  // = 2
     }
     return HOOK_EXIT_CODES.BLOCKING_ERROR;
+  } finally {
+    // Restore stderr for non-hook code paths (e.g., when skipExit is true and process continues as worker)
+    process.stderr.write = originalStderrWrite;
   }
 }

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/constants/observation-metadata.ts

@@ -1,19 +0,0 @@
-/**
- * Observation metadata constants
- * Shared across hooks, worker service, and UI components
- *
- * Note: These are fallback defaults for the code mode.
- * Actual observation types and concepts are defined per-mode in the modes/ directory.
- */
-
-/**
- * Default observation types (comma-separated string for settings)
- * Uses code mode defaults as fallback
- */
-export const DEFAULT_OBSERVATION_TYPES_STRING = 'bugfix,feature,refactor,discovery,decision,change';
-
-/**
- * Default observation concepts (comma-separated string for settings)
- * Uses code mode defaults as fallback
- */
-export const DEFAULT_OBSERVATION_CONCEPTS_STRING = 'how-it-works,why-it-exists,what-changed,problem-solution,gotcha,pattern,trade-off';

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,173 @@
+/**
+ * IDE Auto-Detection
+ *
+ * Detects which AI coding IDEs / tools are installed on the system by
+ * probing known config directories and checking for binaries in PATH.
+ *
+ * Pure Node.js — no Bun APIs used.
+ */
+import { execSync } from 'child_process';
+import { existsSync, readdirSync } from 'fs';
+import { homedir } from 'os';
+import { join } from 'path';
+import { IS_WINDOWS } from '../utils/paths.js';
+
+// ---------------------------------------------------------------------------
+// IDE type and metadata
+// ---------------------------------------------------------------------------
+
+export interface IDEInfo {
+  /** Machine-readable identifier. */
+  id: string;
+  /** Human-readable label for display in prompts. */
+  label: string;
+  /** Whether the IDE was detected on this system. */
+  detected: boolean;
+  /** Whether claude-mem has implemented setup for this IDE. */
+  supported: boolean;
+  /** Short hint text shown in the multi-select. */
+  hint?: string;
+}
+
+// ---------------------------------------------------------------------------
+// PATH helper
+// ---------------------------------------------------------------------------
+
+function isCommandInPath(command: string): boolean {
+  try {
+    const whichCommand = IS_WINDOWS ? 'where' : 'which';
+    execSync(`${whichCommand} ${command}`, { stdio: 'pipe' });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+// ---------------------------------------------------------------------------
+// VS Code extension directory scanner
+// ---------------------------------------------------------------------------
+
+function hasVscodeExtension(extensionNameFragment: string): boolean {
+  const extensionsDirectory = join(homedir(), '.vscode', 'extensions');
+  if (!existsSync(extensionsDirectory)) return false;
+  try {
+    const entries = readdirSync(extensionsDirectory);
+    return entries.some((entry) => entry.toLowerCase().includes(extensionNameFragment.toLowerCase()));
+  } catch {
+    return false;
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Detection map
+// ---------------------------------------------------------------------------
+
+/**
+ * Detect all known IDEs and return an array of `IDEInfo` objects.
+ * Each entry indicates whether the IDE was found and whether claude-mem
+ * currently supports setting it up.
+ */
+export function detectInstalledIDEs(): IDEInfo[] {
+  const home = homedir();
+
+  return [
+    {
+      id: 'claude-code',
+      label: 'Claude Code',
+      detected: existsSync(join(home, '.claude')),
+      supported: true,
+      hint: 'recommended',
+    },
+    {
+      id: 'gemini-cli',
+      label: 'Gemini CLI',
+      detected: existsSync(join(home, '.gemini')),
+      supported: true,
+    },
+    {
+      id: 'opencode',
+      label: 'OpenCode',
+      detected:
+        existsSync(join(home, '.config', 'opencode')) || isCommandInPath('opencode'),
+      supported: true,
+      hint: 'plugin-based integration',
+    },
+    {
+      id: 'openclaw',
+      label: 'OpenClaw',
+      detected: existsSync(join(home, '.openclaw')),
+      supported: true,
+      hint: 'plugin-based integration',
+    },
+    {
+      id: 'windsurf',
+      label: 'Windsurf',
+      detected: existsSync(join(home, '.codeium', 'windsurf')),
+      supported: true,
+    },
+    {
+      id: 'codex-cli',
+      label: 'Codex CLI',
+      detected: existsSync(join(home, '.codex')),
+      supported: true,
+      hint: 'transcript-based integration',
+    },
+    {
+      id: 'cursor',
+      label: 'Cursor',
+      detected: existsSync(join(home, '.cursor')),
+      supported: true,
+      hint: 'hooks + MCP integration',
+    },
+    {
+      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,564 @@
+/**
+ * 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': {
+        const { installCursorHooks, configureCursorMcp } = await import('../../services/integrations/CursorHooksInstaller.js');
+        const cursorResult = await installCursorHooks('user');
+        if (cursorResult === 0) {
+          const mcpResult = configureCursorMcp('user');
+          if (mcpResult === 0) {
+            log.success('Cursor: hooks + MCP installed.');
+          } else {
+            log.success('Cursor: hooks installed (MCP setup failed — run `npx claude-mem cursor mcp` to retry).');
+          }
+        } else {
+          log.error('Cursor: hook installation failed.');
+          failedIDEs.push(ideId);
+        }
+        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!');
+    }
+  }
+}