chore: bump version to 10.5.3

Adds a new claude-mem mode tailored for law school study sessions, with
observation types for case holdings, issue patterns, prof frameworks,
doctrine/rule synthesis, argument structures, and cross-case connections.
Includes a chill variant and a CLAUDE.md template for use as a legal
study partner.

Co-authored-by: Claude Sonnet 4.6 <noreply@anthropic.com>

.claude-plugin/marketplace.json

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

.claude-plugin/plugin.json

@@ -0,0 +1,17 @@
+{
+  "name": "claude-mem",
+  "version": "10.4.1",
+  "description": "Persistent memory system for Claude Code - seamlessly preserve context across sessions",
+  "author": {
+    "name": "Alex Newman"
+  },
+  "repository": "https://github.com/thedotmack/claude-mem",
+  "license": "AGPL-3.0",
+  "keywords": [
+    "memory",
+    "context",
+    "persistence",
+    "hooks",
+    "mcp"
+  ]
+}

.claude/plans/2026-01-05-fix-81-test-failures.md

@@ -1,299 +0,0 @@
-# Plan: Fix 81 Test Failures from Incomplete Logger Mocks
-
-## Problem Summary
-
-**Root Cause**: NOT circular dependency (which is handled gracefully), but **incomplete logger mocks** that pollute across test files when Bun runs tests in alphabetical order.
-
-When `tests/context/` runs before `tests/utils/`, the incomplete mocks replace the real logger module globally, causing subsequent tests to fail with `TypeError: logger.formatTool is not a function`.
-
-## Phase 0: Documentation Discovery (COMPLETED)
-
-### Sources Consulted
-- `src/utils/logger.ts` - Full logger interface (lines 136, 289-373)
-- `tests/context/context-builder.test.ts` - Mock pattern (lines 22-29)
-- `tests/context/observation-compiler.test.ts` - Mock pattern (lines 4-10)
-- `tests/server/server.test.ts` - Mock pattern (lines 4-11)
-- `tests/server/error-handler.test.ts` - Mock pattern (lines 5-12)
-- `tests/worker/agents/response-processor.test.ts` - Mock pattern (lines 32-39)
-
-### Logger Methods (Complete List)
-All 11 methods that must be in any logger mock:
-1. `formatTool(toolName: string, toolInput?: any): string` (line 136)
-2. `debug(component, message, context?, data?): void` (line 289)
-3. `info(component, message, context?, data?): void` (line 293)
-4. `warn(component, message, context?, data?): void` (line 297)
-5. `error(component, message, context?, data?): void` (line 301)
-6. `dataIn(component, message, context?, data?): void` (line 308)
-7. `dataOut(component, message, context?, data?): void` (line 315)
-8. `success(component, message, context?, data?): void` (line 322)
-9. `failure(component, message, context?, data?): void` (line 329)
-10. `timing(component, message, durationMs, context?): void` (line 336)
-11. `happyPathError<T>(message, context?): T` (line 362)
-
-### Files Requiring Updates
-1. `tests/context/observation-compiler.test.ts` (lines 4-10)
-2. `tests/context/context-builder.test.ts` (lines 22-29)
-3. `tests/server/server.test.ts` (lines 4-11)
-4. `tests/server/error-handler.test.ts` (lines 5-12)
-5. `tests/worker/agents/response-processor.test.ts` (lines 32-39)
-
----
-
-## Phase 1: Create Shared Logger Mock Utility
-
-### Objective
-Create a reusable complete logger mock to avoid duplication and ensure consistency.
-
-### Implementation
-
-**Create new file**: `tests/test-utils/mock-logger.ts`
-
-```typescript
-/**
- * Complete logger mock for tests.
- * Includes ALL logger methods to prevent mock pollution across test files.
- */
-import { mock } from 'bun:test';
-
-export function createMockLogger() {
-  return {
-    logger: {
-      // Core logging methods
-      debug: mock(() => {}),
-      info: mock(() => {}),
-      warn: mock(() => {}),
-      error: mock(() => {}),
-
-      // Data flow logging
-      dataIn: mock(() => {}),
-      dataOut: mock(() => {}),
-
-      // Status logging
-      success: mock(() => {}),
-      failure: mock(() => {}),
-
-      // Performance logging
-      timing: mock(() => {}),
-
-      // Tool formatting - returns string
-      formatTool: mock((toolName: string, _toolInput?: any) => toolName),
-
-      // Error helper - returns the message
-      happyPathError: mock((message: string, _context?: any) => message),
-    },
-  };
-}
-```
-
-### Verification Checklist
-- [ ] File created at `tests/test-utils/mock-logger.ts`
-- [ ] All 11 logger methods included
-- [ ] `formatTool` returns string (not void)
-- [ ] `happyPathError` returns the message (not void)
-- [ ] File compiles without errors: `bunx tsc --noEmit tests/test-utils/mock-logger.ts`
-
-### Anti-Patterns to Avoid
-- ❌ Don't forget `formatTool` - it returns a string, not void
-- ❌ Don't forget `happyPathError` - it's generic and returns the message
-- ❌ Don't use `() => {}` for methods that return values
-
----
-
-## Phase 2: Update Affected Test Files
-
-### Objective
-Replace incomplete logger mocks with the complete shared mock.
-
-### Files to Update (5 total)
-
-#### 2.1 `tests/context/observation-compiler.test.ts`
-
-**Current (lines 4-10)**:
-```typescript
-mock.module('../../src/utils/logger.js', () => ({
-  logger: {
-    debug: mock(() => {}),
-    failure: mock(() => {}),
-    error: mock(() => {}),
-  },
-}));
-```
-
-**Replace with**:
-```typescript
-import { createMockLogger } from '../test-utils/mock-logger.js';
-
-mock.module('../../src/utils/logger.js', () => createMockLogger());
-```
-
-#### 2.2 `tests/context/context-builder.test.ts`
-
-**Current (lines 22-29)**:
-```typescript
-mock.module('../../src/utils/logger.js', () => ({
-  logger: {
-    debug: mock(() => {}),
-    failure: mock(() => {}),
-    error: mock(() => {}),
-    info: mock(() => {}),
-  },
-}));
-```
-
-**Replace with**:
-```typescript
-import { createMockLogger } from '../test-utils/mock-logger.js';
-
-mock.module('../../src/utils/logger.js', () => createMockLogger());
-```
-
-#### 2.3 `tests/server/server.test.ts`
-
-**Current (lines 4-11)**:
-```typescript
-mock.module('../../src/utils/logger.js', () => ({
-  logger: {
-    info: () => {},
-    debug: () => {},
-    warn: () => {},
-    error: () => {},
-  },
-}));
-```
-
-**Replace with**:
-```typescript
-import { createMockLogger } from '../test-utils/mock-logger.js';
-
-mock.module('../../src/utils/logger.js', () => createMockLogger());
-```
-
-#### 2.4 `tests/server/error-handler.test.ts`
-
-**Current (lines 5-12)**:
-```typescript
-mock.module('../../src/utils/logger.js', () => ({
-  logger: {
-    info: () => {},
-    debug: () => {},
-    warn: () => {},
-    error: () => {},
-  },
-}));
-```
-
-**Replace with**:
-```typescript
-import { createMockLogger } from '../test-utils/mock-logger.js';
-
-mock.module('../../src/utils/logger.js', () => createMockLogger());
-```
-
-#### 2.5 `tests/worker/agents/response-processor.test.ts`
-
-**Current (lines 32-39)**:
-```typescript
-mock.module('../../../src/utils/logger.js', () => ({
-  logger: {
-    info: () => {},
-    debug: () => {},
-    warn: () => {},
-    error: () => {},
-  },
-}));
-```
-
-**Replace with**:
-```typescript
-import { createMockLogger } from '../../test-utils/mock-logger.js';
-
-mock.module('../../../src/utils/logger.js', () => createMockLogger());
-```
-
-### Verification Checklist
-- [ ] All 5 files updated with import statement
-- [ ] All 5 files use `createMockLogger()` instead of inline mock
-- [ ] Import paths are correct (relative to each file's location)
-- [ ] Each file still has `mock.module` BEFORE the module imports it mocks
-
-### Anti-Patterns to Avoid
-- ❌ Don't place import AFTER the mock.module call
-- ❌ Don't use wrong relative path (../test-utils vs ../../test-utils)
-- ❌ Don't forget the .js extension in imports
-
----
-
-## Phase 3: Verification
-
-### Objective
-Confirm all 81 failures are fixed.
-
-### Test Commands
-
-```bash
-# 1. Run individual test groups first
-bun test tests/context/
-bun test tests/server/
-bun test tests/utils/
-bun test tests/shared/
-bun test tests/worker/
-
-# 2. Run full suite
-bun test
-
-# 3. Verify specific test counts
-# Expected: 733+ tests pass (was 652 before)
-```
-
-### Verification Checklist
-- [ ] `bun test tests/context/` - all pass
-- [ ] `bun test tests/server/` - all pass
-- [ ] `bun test tests/utils/` - all pass (including 56 formatTool tests)
-- [ ] `bun test tests/shared/` - all pass (including 27 settings tests)
-- [ ] `bun test` - 730+ tests pass, 0 failures
-- [ ] No `TypeError: logger.formatTool is not a function` errors
-
-### Anti-Pattern Grep Checks
-
-```bash
-# Check no incomplete logger mocks remain
-grep -r "logger: {" tests/ --include="*.ts" | grep -v mock-logger
-
-# Verify all test files use createMockLogger
-grep -r "createMockLogger" tests/ --include="*.ts"
-```
-
----
-
-## Phase 4: Commit
-
-### Commit Message
-
-```
-fix(tests): complete logger mocks to prevent cross-test pollution
-
-The 81 test failures were caused by incomplete logger mocks that
-polluted the module cache when tests ran in alphabetical order.
-
-Changes:
-- Create shared mock-logger.ts with all 11 logger methods
-- Update 5 test files to use complete mock
-- Fix TypeError: logger.formatTool is not a function
-
-🤖 Generated with [Claude Code](https://claude.com/claude-code)
-
-Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
-```
-
----
-
-## Summary
-
-| Phase | Files Changed | Purpose |
-|-------|--------------|---------|
-| 1 | 1 new file | Create shared mock utility |
-| 2 | 5 files | Update to use shared mock |
-| 3 | 0 files | Verification only |
-| 4 | 0 files | Commit |
-
-**Total**: 6 files changed, fixing all 81 test failures.

.claude/plans/animated-installer.md

@@ -0,0 +1,371 @@
+# Comprehensive Claude-Mem Installer with @clack/prompts
+
+## Overview
+
+Build a beautiful, animated CLI installer for claude-mem using `@clack/prompts` (v1.0.1). Distributable via `npx claude-mem-installer` and `curl -fsSL https://install.cmem.ai | bash`. Replaces the need for users to manually clone, build, configure settings, and start the worker.
+
+**Worktree**: `feat/animated-installer` at `.claude/worktrees/animated-installer`
+
+---
+
+## Phase 0: Documentation & API Reference
+
+### Allowed APIs (@clack/prompts v1.0.1, ESM-only)
+
+| API | Signature | Use Case |
+|-----|-----------|----------|
+| `intro(title?)` | `void` | Opening banner |
+| `outro(message?)` | `void` | Completion message |
+| `cancel(message?)` | `void` | User cancelled |
+| `isCancel(value)` | `boolean` | Check if user pressed Ctrl+C |
+| `text(opts)` | `Promise<string \| symbol>` | API key input, port, data dir |
+| `password(opts)` | `Promise<string \| symbol>` | API key input (masked) |
+| `select(opts)` | `Promise<Value \| symbol>` | Provider, model, auth method |
+| `multiselect(opts)` | `Promise<Value[] \| symbol>` | IDE selection, observation types |
+| `confirm(opts)` | `Promise<boolean \| symbol>` | Enable Chroma, start worker |
+| `spinner()` | `SpinnerResult` | Installing deps, building, starting worker |
+| `progress(opts)` | `ProgressResult` | Multi-step installation progress |
+| `tasks(tasks[])` | `Promise<void>` | Sequential install steps |
+| `group(prompts, opts)` | `Promise<Results>` | Chain prompts with shared results |
+| `note(message, title)` | `void` | Display settings summary, next steps |
+| `log.info/success/warn/error(msg)` | `void` | Status messages |
+| `box(message, title, opts)` | `void` | Welcome box, completion summary |
+
+### Anti-Patterns
+- Do NOT use `require()` — package is ESM-only
+- Do NOT call prompts without TTY check first — hangs indefinitely in non-TTY
+- Do NOT forget `isCancel()` check after every prompt (or use `group()` with `onCancel`)
+- Do NOT use `chalk` — use `picocolors` (clack's dep) for consistency
+- `text()` has no numeric mode — validate manually for port numbers
+- `spinner.stop()` does not accept status codes — use `spinner.error()` for failures
+
+### Distribution Patterns
+- **npx**: `package.json` `bin` field → `"./dist/index.js"`, file needs `#!/usr/bin/env node`
+- **curl|bash**: Shell bootstrap downloads JS, runs `node script.js` directly (preserves TTY)
+- **esbuild**: Bundle to single ESM file, `platform: 'node'`, `banner` for shebang
+
+### Key Source Files to Reference
+- Settings defaults: `src/shared/SettingsDefaultsManager.ts` (lines 73-125)
+- Settings validation: `src/services/server/SettingsRoutes.ts`
+- Worker startup: `src/services/worker-service.ts` (lines 337-359)
+- Health check: `src/services/infrastructure/HealthMonitor.ts`
+- Plugin registration: `plugin/.claude-plugin/plugin.json`, `.claude-plugin/marketplace.json`
+- Marketplace sync: `scripts/sync-marketplace.cjs`
+- Cursor integration: `src/services/integrations/CursorHooksInstaller.ts`
+- Existing OpenClaw installer: `install/public/openclaw.sh` (reference for logic, not code to copy)
+
+---
+
+## Phase 1: Project Scaffolding
+
+**Goal**: Set up the installer package structure with build tooling.
+
+### Tasks
+
+1. **Create directory structure** in the worktree:
+   ```
+   installer/
+   ├── src/
+   │   ├── index.ts              # Entry point with TTY guard
+   │   ├── steps/
+   │   │   ├── welcome.ts        # intro + version check
+   │   │   ├── dependencies.ts   # bun, uv, git checks
+   │   │   ├── ide-selection.ts  # IDE picker + registration
+   │   │   ├── provider.ts       # AI provider + API key
+   │   │   ├── settings.ts       # Additional settings config
+   │   │   ├── install.ts        # Clone, build, register plugin
+   │   │   ├── worker.ts         # Start worker + health check
+   │   │   └── complete.ts       # Summary + next steps
+   │   └── utils/
+   │       ├── system.ts         # OS detection, command runner
+   │       ├── dependencies.ts   # bun/uv/git install helpers
+   │       └── settings-writer.ts # Write ~/.claude-mem/settings.json
+   ├── build.mjs                 # esbuild config
+   ├── package.json              # bin, type: module, deps
+   └── tsconfig.json
+   ```
+
+2. **Create `package.json`**:
+   ```json
+   {
+     "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" }
+   }
+   ```
+
+3. **Create `build.mjs`**:
+   - esbuild bundle: `entryPoints: ['src/index.ts']`, `format: 'esm'`, `platform: 'node'`, `target: 'node18'`
+   - Banner: `#!/usr/bin/env node`
+   - Output: `dist/index.js`
+
+4. **Create `tsconfig.json`**:
+   - `module: "ESNext"`, `target: "ES2022"`, `moduleResolution: "bundler"`
+
+5. **Run `npm install`** in installer/ directory
+
+### Verification
+- [ ] `node build.mjs` succeeds
+- [ ] `dist/index.js` exists with shebang
+- [ ] `node dist/index.js` runs (even if empty installer)
+
+---
+
+## Phase 2: Entry Point + Welcome Screen
+
+**Goal**: Create the main entry point with TTY detection and a beautiful welcome screen.
+
+### Tasks
+
+1. **`src/index.ts`** — Entry point:
+   - TTY guard: if `!process.stdin.isTTY`, print error directing user to `npx claude-mem-installer`, exit 1
+   - Import and call `runInstaller()` from steps
+   - Top-level catch → `p.cancel()` + exit 1
+
+2. **`src/steps/welcome.ts`** — Welcome step:
+   - `p.intro()` with styled title using picocolors: `" claude-mem installer "`
+   - Display version info via `p.log.info()`
+   - Check if already installed (detect `~/.claude-mem/settings.json` and `~/.claude/plugins/marketplaces/thedotmack/`)
+   - If upgrade detected, `p.confirm()`: "claude-mem is already installed. Upgrade?"
+   - `p.select()` for install mode: Fresh Install vs Upgrade vs Configure Only
+
+3. **`src/utils/system.ts`** — System utilities:
+   - `detectOS()`: returns 'macos' | 'linux' | 'windows'
+   - `commandExists(cmd)`: checks if command is in PATH
+   - `runCommand(cmd, args)`: executes shell command, returns { stdout, stderr, exitCode }
+   - `expandHome(path)`: resolves `~` to home directory
+
+### Verification
+- [ ] Running `node dist/index.js` shows intro banner
+- [ ] Ctrl+C triggers cancel message
+- [ ] Non-TTY (piped) shows error and exits
+
+---
+
+## Phase 3: Dependency Checks
+
+**Goal**: Check and install required dependencies (Bun, uv, git, Node.js version).
+
+### Tasks
+
+1. **`src/steps/dependencies.ts`** — Dependency checker:
+   - Use `p.tasks()` to check each dependency sequentially with animated spinners:
+     - **Node.js**: Verify >= 18.0.0 via `process.version`
+     - **git**: `commandExists('git')`, show install instructions per OS if missing
+     - **Bun**: Check PATH + common locations (`~/.bun/bin/bun`, `/usr/local/bin/bun`, `/opt/homebrew/bin/bun`). Min version 1.1.14. Offer to auto-install from `https://bun.sh/install`
+     - **uv**: Check PATH + common locations (`~/.local/bin/uv`, `~/.cargo/bin/uv`). Offer to auto-install from `https://astral.sh/uv/install.sh`
+   - For missing deps: `p.confirm()` to auto-install, or show manual instructions
+   - After install attempts, re-verify each dep
+
+2. **`src/utils/dependencies.ts`** — Install helpers:
+   - `installBun()`: downloads and runs bun install script
+   - `installUv()`: downloads and runs uv install script
+   - `findBinary(name, extraPaths[])`: searches PATH + known locations
+   - `checkVersion(binary, minVersion)`: parses `--version` output
+
+### Verification
+- [ ] Shows green checkmarks for found dependencies
+- [ ] Shows yellow warnings for missing deps with install option
+- [ ] Auto-install actually installs bun/uv when confirmed
+- [ ] Fails gracefully if git is missing (can't auto-install)
+
+---
+
+## Phase 4: IDE Selection & Provider Configuration
+
+**Goal**: Let user choose IDEs and configure AI provider with API keys.
+
+### Tasks
+
+1. **`src/steps/ide-selection.ts`** — IDE picker:
+   - `p.multiselect()` with options:
+     - Claude Code (default selected, hint: "recommended")
+     - Cursor
+     - Windsurf (hint: "coming soon", disabled: true)
+   - For Claude Code: explain plugin will be registered via marketplace
+   - For Cursor: explain hooks will be installed via CursorHooksInstaller pattern
+   - Store selections for later installation steps
+
+2. **`src/steps/provider.ts`** — AI provider configuration:
+   - `p.select()` for provider:
+     - **Claude** (hint: "recommended — uses your Claude subscription")
+     - **Gemini** (hint: "free tier available")
+     - **OpenRouter** (hint: "free models available")
+   - **If Claude selected**:
+     - `p.select()` for auth method: "CLI (Max Plan subscription)" vs "API Key"
+     - If API key: `p.password()` for key input
+   - **If Gemini selected**:
+     - `p.password()` for API key (required)
+     - `p.select()` for model: gemini-2.5-flash-lite (default), gemini-2.5-flash, gemini-3-flash-preview
+     - `p.confirm()` for rate limiting (default: true)
+   - **If OpenRouter selected**:
+     - `p.password()` for API key (required)
+     - `p.text()` for model (default: `xiaomi/mimo-v2-flash:free`)
+   - Validate API keys where possible (non-empty, format check)
+
+### Verification
+- [ ] Multiselect allows picking multiple IDEs
+- [ ] Provider selection shows correct follow-up prompts
+- [ ] API keys are masked during input
+- [ ] Cancel at any step triggers graceful exit
+
+---
+
+## Phase 5: Settings Configuration
+
+**Goal**: Configure additional settings with sensible defaults.
+
+### Tasks
+
+1. **`src/steps/settings.ts`** — Settings wizard:
+   - `p.confirm()`: "Use default settings?" (recommended) — if yes, skip detailed config
+   - If customizing, use `p.group()` for:
+     - **Worker port**: `p.text()` with default 37777, validate 1024-65535
+     - **Data directory**: `p.text()` with default `~/.claude-mem`
+     - **Context observations**: `p.text()` with default 50, validate 1-200
+     - **Log level**: `p.select()` — DEBUG, INFO (default), WARN, ERROR
+     - **Python version**: `p.text()` with default 3.13
+     - **Chroma vector search**: `p.confirm()` (default: true)
+       - If yes, `p.select()` mode: local (default) vs remote
+       - If remote: `p.text()` for host, port, `p.confirm()` for SSL
+   - Show settings summary via `p.note()` before proceeding
+
+2. **`src/utils/settings-writer.ts`** — Write settings:
+   - Build flat key-value settings object matching SettingsDefaultsManager schema
+   - Merge with existing settings if upgrading (preserve user customizations)
+   - Write to `~/.claude-mem/settings.json`
+   - Create `~/.claude-mem/` directory if it doesn't exist
+
+### Verification
+- [ ] Default settings mode skips all detailed prompts
+- [ ] Custom settings validates all inputs
+- [ ] Settings file written matches SettingsDefaultsManager schema exactly
+- [ ] Existing settings preserved on upgrade
+
+---
+
+## Phase 6: Installation Execution
+
+**Goal**: Clone repo, build plugin, register with IDEs, start worker.
+
+### Tasks
+
+1. **`src/steps/install.ts`** — Installation runner:
+   - Use `p.tasks()` for visual progress:
+     - **"Cloning claude-mem repository"**: `git clone --depth 1 https://github.com/thedotmack/claude-mem.git` to temp dir
+     - **"Installing dependencies"**: `npm install` in cloned repo
+     - **"Building plugin"**: `npm run build` in cloned repo
+     - **"Registering plugin"**: Copy plugin files to `~/.claude/plugins/marketplaces/thedotmack/`
+       - Create marketplace.json, plugin.json structure
+       - Register in `~/.claude/plugins/known_marketplaces.json`
+       - Add to `~/.claude/plugins/installed_plugins.json`
+       - Enable in `~/.claude/settings.json` under `enabledPlugins`
+     - **"Installing dependencies"** (in marketplace dir): `npm install`
+   - For Cursor (if selected):
+     - **"Configuring Cursor hooks"**: Run Cursor hooks installer logic
+     - Write hooks.json to `~/.cursor/` or project-level `.cursor/`
+     - Configure MCP in `.cursor/mcp.json`
+
+2. **`src/steps/worker.ts`** — Worker startup:
+   - Use `p.spinner()` for worker startup:
+     - Start worker: `bun plugin/scripts/worker-service.cjs` (from marketplace dir)
+     - Write PID file to `~/.claude-mem/worker.pid`
+   - Two-stage health check (copy pattern from OpenClaw installer):
+     - Stage 1: Poll `/api/health` — spinner message: "Starting worker service..."
+     - Stage 2: Poll `/api/readiness` — spinner message: "Initializing database..."
+     - Budget: 30 attempts, 1 second apart
+     - On success: `spinner.stop("Worker running on port {port}")`
+     - On failure: `spinner.error("Worker failed to start")`, show log path
+
+### Verification
+- [ ] Plugin files exist at `~/.claude/plugins/marketplaces/thedotmack/`
+- [ ] known_marketplaces.json updated
+- [ ] installed_plugins.json updated
+- [ ] settings.json has enabledPlugins entry
+- [ ] Worker responds to `/api/health` with 200
+- [ ] Worker responds to `/api/readiness` with 200
+
+---
+
+## Phase 7: Completion & Summary
+
+**Goal**: Show success screen with configuration summary and next steps.
+
+### Tasks
+
+1. **`src/steps/complete.ts`** — Completion screen:
+   - `p.note()` with configuration summary:
+     - Provider + model
+     - IDEs configured
+     - Data directory
+     - Worker port
+     - Chroma enabled/disabled
+   - `p.note()` with next steps:
+     - "Open Claude Code and start a conversation — memory is automatic!"
+     - "View your memories: http://localhost:{port}"
+     - "Search past work: use /mem-search in Claude Code"
+     - If Cursor: "Open Cursor — hooks are active in your projects"
+   - `p.outro()` with styled completion message
+
+### Verification
+- [ ] Summary accurately reflects chosen settings
+- [ ] URLs use correct port from settings
+- [ ] Next steps are relevant to selected IDEs
+
+---
+
+## Phase 8: curl|bash Bootstrap Script
+
+**Goal**: Create the shell bootstrap script for `curl -fsSL https://install.cmem.ai | bash`.
+
+### Tasks
+
+1. **`install/public/install.sh`** — Bootstrap script:
+   - Check for Node.js >= 18 (required to run the installer)
+   - Download bundled installer JS to temp file
+   - Execute with `node` directly (preserves TTY for @clack/prompts)
+   - Cleanup temp file on exit (trap)
+   - Support `--non-interactive` flag passthrough
+   - Support `--provider=X --api-key=Y` flag passthrough
+
+2. **Update `install/vercel.json`** to serve `install.sh` alongside `openclaw.sh`
+
+### Verification
+- [ ] `curl -fsSL https://install.cmem.ai | bash` downloads and runs installer
+- [ ] Interactive prompts work after curl download
+- [ ] Temp file cleaned up on success and failure
+- [ ] Flags pass through correctly
+
+---
+
+## Phase 9: Final Verification
+
+### Checks
+- [ ] `npm run build` in installer/ produces single-file `dist/index.js`
+- [ ] `node dist/index.js` runs full wizard flow
+- [ ] Fresh install on clean system works end-to-end
+- [ ] Upgrade path preserves existing settings
+- [ ] Ctrl+C at any step exits cleanly
+- [ ] Non-TTY shows error message
+- [ ] All settings written match SettingsDefaultsManager.ts defaults schema
+- [ ] Worker health check succeeds after install
+- [ ] Plugin appears in Claude Code plugin list
+- [ ] grep for deprecated/non-existent APIs returns 0 results
+- [ ] No `require()` calls in source (ESM-only)
+- [ ] No `chalk` imports (use picocolors)

.claude/plans/bugfix-env-auth.md

@@ -1,176 +0,0 @@
-# Bugfix Plan: Observer Sessions Authentication Failure
-
-## Problem Summary
-
-Observer sessions fail with "Invalid API key · Please run /login" because the `CLAUDE_CONFIG_DIR` environment variable is being set to an isolated directory (`~/.claude-mem/observer-config/`) that lacks authentication credentials.
-
-## Root Cause
-
-**File:** `src/services/worker/ProcessRegistry.ts` (lines 207-211)
-
-```typescript
-const isolatedEnv = {
-  ...spawnOptions.env,
-  CLAUDE_CONFIG_DIR: OBSERVER_CONFIG_DIR  // <-- This isolates auth credentials!
-};
-```
-
-This was added in Issue #832 to prevent observer sessions from polluting the `claude --resume` list. However, it also isolates the authentication credentials, breaking the SDK's ability to authenticate with the Anthropic API.
-
-## Evidence
-
-1. Running Claude with alternate config dir reproduces the error:
-   ```bash
-   CLAUDE_CONFIG_DIR=/tmp/test-claude claude --print "hello"
-   # Output: Invalid API key · Please run /login
-   ```
-
-2. The observer config directory exists but only has cached feature flags, no authentication:
-   - `~/.claude-mem/observer-config/.claude.json` - feature flags only
-   - No credentials copied from main `~/.claude/` directory
-
-## Solution
-
-The fix must allow authentication while still isolating session history. Claude Code stores different data types in `CLAUDE_CONFIG_DIR`:
-- Authentication credentials (needed)
-- Session history/resume list (should be isolated)
-- Feature flags and settings (can be shared or isolated)
-
-**Approach:** Do NOT override `CLAUDE_CONFIG_DIR`. Instead, find an alternative solution for Issue #832.
-
-### Alternative Approaches for Session Isolation
-
-1. **Use `--no-resume` flag** (if SDK supports it) - Prevent observer sessions from being resumable
-2. **Accept pollution** - Observer sessions in resume list may be acceptable tradeoff
-3. **Post-hoc cleanup** - Clean up observer session entries from history after completion
-4. **SDK parameter** - Check if SDK has a session isolation option that doesn't affect auth
-
----
-
-## Phase 0: Documentation Discovery
-
-### Objective
-Understand SDK options for session isolation without breaking authentication.
-
-### Tasks
-1. Read SDK documentation/source for:
-   - Available `query()` options
-   - Session isolation mechanisms
-   - Authentication handling
-
-2. Read Issue #832 context:
-   - What was the original problem?
-   - How bad was the pollution?
-   - Are there alternative solutions mentioned?
-
-### Verification
-- [ ] List all `query()` options available
-- [ ] Identify if `--no-resume` or equivalent exists
-- [ ] Document the tradeoffs
-
----
-
-## Phase 1: Fix Authentication
-
-### Objective
-Remove the `CLAUDE_CONFIG_DIR` override to restore authentication.
-
-### File to Modify
-`src/services/worker/ProcessRegistry.ts`
-
-### Change
-Remove lines 207-211 that override `CLAUDE_CONFIG_DIR`:
-
-**Before:**
-```typescript
-const isolatedEnv = {
-  ...spawnOptions.env,
-  CLAUDE_CONFIG_DIR: OBSERVER_CONFIG_DIR
-};
-```
-
-**After:**
-```typescript
-const isolatedEnv = {
-  ...spawnOptions.env
-  // CLAUDE_CONFIG_DIR removed - observer sessions need access to auth credentials
-  // Session isolation addressed via [alternative approach]
-};
-```
-
-### Verification
-- [ ] Build succeeds: `npm run build`
-- [ ] Observer sessions authenticate successfully
-- [ ] Observations are saved to database
-
----
-
-## Phase 2: Address Session Isolation (Issue #832)
-
-### Objective
-Find alternative solution to prevent observer sessions from polluting `claude --resume` list.
-
-### Options to Evaluate
-
-1. **Option A: Accept the tradeoff**
-   - Observer sessions appear in resume list but users can ignore them
-   - No code changes needed beyond Phase 1
-
-2. **Option B: Use isSynthetic flag**
-   - If SDK has a flag to mark sessions as non-resumable, use it
-   - Requires SDK documentation review
-
-3. **Option C: Post-processing cleanup**
-   - After session ends, remove observer entries from history
-   - More complex, may have race conditions
-
-### Decision Point
-After Phase 0 documentation review, choose the appropriate option.
-
-### Verification
-- [ ] Chosen approach documented
-- [ ] If code changes made, tests pass
-- [ ] Observer sessions either isolated OR tradeoff accepted
-
----
-
-## Phase 3: Testing
-
-### Manual Tests
-1. Start a new Claude Code session with the plugin
-2. Verify observations are being saved (check logs)
-3. Check that no "Invalid API key" errors appear
-4. Verify `claude --resume` behavior (acceptable level of observer entries)
-
-### Verification Checklist
-- [ ] `npm run build` succeeds
-- [ ] Worker service starts without errors
-- [ ] Observations save to database
-- [ ] No authentication errors in logs
-- [ ] Issue #832 regression acceptable or addressed
-
----
-
-## Anti-Patterns to Avoid
-
-1. **DO NOT** add `ANTHROPIC_API_KEY` to environment - authentication is handled by Claude Code's built-in credential management
-2. **DO NOT** copy credential files to observer config dir - credentials may be in keychain or other secure storage
-3. **DO NOT** try to "fix" authentication by adding API key loading - that creates Issue #588 (unexpected API charges)
-
----
-
-## Files Involved
-
-| File | Purpose |
-|------|---------|
-| `src/services/worker/ProcessRegistry.ts` | Contains the problematic `CLAUDE_CONFIG_DIR` override |
-| `src/shared/paths.ts` | Defines `OBSERVER_CONFIG_DIR` constant |
-| `src/services/worker/SDKAgent.ts` | Uses `createPidCapturingSpawn` which sets the env |
-
----
-
-## Risk Assessment
-
-**Low Risk:** Removing the `CLAUDE_CONFIG_DIR` override is a simple, targeted change.
-
-**Regression Risk (Issue #832):** Observer sessions may appear in `claude --resume` list again. This is a cosmetic issue vs. complete authentication failure, so the tradeoff favors removing the override.

.claude/plans/claude-md-path-validation-fix.md

@@ -1,262 +0,0 @@
-# CLAUDE.md Path Validation Bug Fix
-
-## Problem Summary
-
-Claude-Mem 9.0's distributed CLAUDE.md feature has a **critical path validation bug** that creates invalid directories when Claude SDK agent outputs non-path strings in file tracking XML tags (`<files_read>`, `<files_modified>`).
-
-### Root Cause
-
-In `src/utils/claude-md-utils.ts:234-239`:
-```typescript
-if (projectRoot && !path.isAbsolute(filePath)) {
-  absoluteFilePath = path.join(projectRoot, filePath);
-}
-```
-
-- `path.isAbsolute('~/.claude-mem/logs')` returns `false` (Node.js doesn't recognize `~`)
-- Code joins: `path.join(projectRoot, '~/.claude-mem/logs')` → `/project/~/.claude-mem/logs`
-- `mkdirSync` creates literal directories
-
-### Invalid Directories Currently in Repo
-
-```
-./~/                              ← literal tilde directory
-./PR #610 on thedotmack/          ← GitHub PR reference
-./git diff for src/               ← git command text
-./https:/code.claude.com/docs/en/ ← URL
-```
-
----
-
-## Implementation Plan
-
-### Phase 1: Add Path Validation Function
-
-**File:** `src/utils/claude-md-utils.ts`
-
-Add new validation function after the imports (around line 16):
-
-```typescript
-/**
- * Validate that a file path is safe for CLAUDE.md generation.
- * Rejects tilde paths, URLs, command-like strings, and paths with invalid chars.
- *
- * @param filePath - The file path to validate
- * @param projectRoot - Optional project root for boundary checking
- * @returns true if path is valid for CLAUDE.md processing
- */
-function isValidPathForClaudeMd(filePath: string, projectRoot?: string): boolean {
-  // Reject empty or whitespace-only
-  if (!filePath || !filePath.trim()) return false;
-
-  // Reject tilde paths (Node.js doesn't expand ~)
-  if (filePath.startsWith('~')) return false;
-
-  // Reject URLs
-  if (filePath.startsWith('http://') || filePath.startsWith('https://')) return false;
-
-  // Reject paths with spaces (likely command text or PR references)
-  if (filePath.includes(' ')) return false;
-
-  // Reject paths with # (GitHub issue/PR references)
-  if (filePath.includes('#')) return false;
-
-  // If projectRoot provided, ensure resolved path stays within project
-  if (projectRoot) {
-    const resolved = path.resolve(projectRoot, filePath);
-    const normalizedRoot = path.resolve(projectRoot);
-    if (!resolved.startsWith(normalizedRoot + path.sep) && resolved !== normalizedRoot) {
-      return false;
-    }
-  }
-
-  return true;
-}
-```
-
-### Phase 2: Integrate Validation in updateFolderClaudeMdFiles
-
-**File:** `src/utils/claude-md-utils.ts`
-
-Modify the file path loop in `updateFolderClaudeMdFiles` (around line 232):
-
-```typescript
-for (const filePath of filePaths) {
-  if (!filePath || filePath === '') continue;
-
-  // VALIDATE PATH BEFORE PROCESSING
-  if (!isValidPathForClaudeMd(filePath, projectRoot)) {
-    logger.debug('FOLDER_INDEX', 'Skipping invalid file path', {
-      filePath,
-      reason: 'Failed path validation'
-    });
-    continue;
-  }
-
-  // ... rest of existing logic unchanged
-}
-```
-
-### Phase 3: Add Unit Tests
-
-**File:** `tests/utils/claude-md-utils.test.ts`
-
-Add new test block after existing tests:
-
-```typescript
-describe('path validation in updateFolderClaudeMdFiles', () => {
-  it('should reject tilde paths', async () => {
-    const fetchMock = mock(() => Promise.resolve({ ok: true } as Response));
-    global.fetch = fetchMock;
-
-    await updateFolderClaudeMdFiles(
-      ['~/.claude-mem/logs/worker.log'],
-      'test-project',
-      37777,
-      tempDir
-    );
-
-    expect(fetchMock).not.toHaveBeenCalled();
-  });
-
-  it('should reject URLs', async () => {
-    const fetchMock = mock(() => Promise.resolve({ ok: true } as Response));
-    global.fetch = fetchMock;
-
-    await updateFolderClaudeMdFiles(
-      ['https://example.com/file.ts'],
-      'test-project',
-      37777,
-      tempDir
-    );
-
-    expect(fetchMock).not.toHaveBeenCalled();
-  });
-
-  it('should reject paths with spaces', async () => {
-    const fetchMock = mock(() => Promise.resolve({ ok: true } as Response));
-    global.fetch = fetchMock;
-
-    await updateFolderClaudeMdFiles(
-      ['PR #610 on thedotmack/CLAUDE.md'],
-      'test-project',
-      37777,
-      tempDir
-    );
-
-    expect(fetchMock).not.toHaveBeenCalled();
-  });
-
-  it('should reject paths with hash symbols', async () => {
-    const fetchMock = mock(() => Promise.resolve({ ok: true } as Response));
-    global.fetch = fetchMock;
-
-    await updateFolderClaudeMdFiles(
-      ['issue#123/file.ts'],
-      'test-project',
-      37777,
-      tempDir
-    );
-
-    expect(fetchMock).not.toHaveBeenCalled();
-  });
-
-  it('should reject path traversal outside project', async () => {
-    const fetchMock = mock(() => Promise.resolve({ ok: true } as Response));
-    global.fetch = fetchMock;
-
-    await updateFolderClaudeMdFiles(
-      ['../../../etc/passwd'],
-      'test-project',
-      37777,
-      tempDir
-    );
-
-    expect(fetchMock).not.toHaveBeenCalled();
-  });
-
-  it('should accept valid relative paths', async () => {
-    const apiResponse = {
-      content: [{ text: '| #123 | 4:30 PM | 🔵 | Test | ~100 |' }]
-    };
-    const fetchMock = mock(() => Promise.resolve({
-      ok: true,
-      json: () => Promise.resolve(apiResponse)
-    } as Response));
-    global.fetch = fetchMock;
-
-    await updateFolderClaudeMdFiles(
-      ['src/utils/logger.ts'],
-      'test-project',
-      37777,
-      tempDir
-    );
-
-    expect(fetchMock).toHaveBeenCalledTimes(1);
-  });
-});
-```
-
-### Phase 4: Update .gitignore
-
-**File:** `.gitignore`
-
-Add at end of file:
-
-```gitignore
-# Prevent literal tilde directories (path validation bug artifacts)
-~*/
-
-# Prevent other malformed path directories
-http*/
-https*/
-```
-
-### Phase 5: Clean Up Invalid Directories
-
-**Command sequence:**
-```bash
-rm -rf "~/."
-rm -rf "PR #610 on thedotmack"
-rm -rf "git diff for src"
-rm -rf "https:"
-```
-
-### Phase 6: Verify and Commit
-
-1. Run test suite: `npm test`
-2. Run build: `npm run build`
-3. Verify no invalid directories remain
-4. Commit with message: `fix: Add path validation to CLAUDE.md distribution to prevent invalid directory creation`
-
----
-
-## Files Modified
-
-| File | Change |
-|------|--------|
-| `src/utils/claude-md-utils.ts` | Add `isValidPathForClaudeMd()` function + integrate in loop |
-| `tests/utils/claude-md-utils.test.ts` | Add 6 new path validation tests |
-| `.gitignore` | Add `~*/`, `http*/`, `https*/` patterns |
-
-## Files Deleted
-
-| Path | Reason |
-|------|--------|
-| `~/` (directory tree) | Invalid literal tilde directory |
-| `PR #610 on thedotmack/` | Invalid PR reference directory |
-| `git diff for src/` | Invalid git command directory |
-| `https:/` | Invalid URL directory |
-
----
-
-## Risk Assessment
-
-**Low Risk:**
-- Validation is additive (only skips invalid paths, doesn't change valid path handling)
-- Existing tests remain unchanged
-- Fire-and-forget design means failures are logged but don't break hooks
-
-**Testing Coverage:**
-- 6 new unit tests covering all rejection cases
-- Existing 27 tests verify valid path behavior unchanged

.claude/plans/cleanup-worker-service-nonsense-logic.md

@@ -1,314 +0,0 @@
-# Plan: Cleanup worker-service.ts Unjustified Logic
-
-**Created:** 2026-01-13
-**Source:** `docs/reports/nonsense-logic.md`
-**Target:** `src/services/worker-service.ts` (813 lines)
-**Goal:** Address 23 identified issues, prioritizing safe deletions first
-
----
-
-## Phase 0: Documentation Discovery (COMPLETED)
-
-### Evidence Gathered
-
-**Exit Code Strategy (CLAUDE.md:44-54):**
-```
-- Exit 0: Success or graceful shutdown (Windows Terminal closes tabs)
-- Exit 1: Non-blocking error
-- Exit 2: Blocking error
-Philosophy: Exit 0 prevents Windows Terminal tab accumulation
-```
-
-**Signal Handler Pattern (ProcessManager.ts:294-317):**
-- Uses mutable reference object `isShuttingDownRef`
-- Factory function `createSignalHandler()` returns handler with embedded state
-- Current implementation has 3-hop indirection
-
-**MCP Client Pattern (worker-service.ts:157-160, ChromaSync.ts:124-136):**
-```typescript
-this.mcpClient = new Client({
-  name: 'worker-search-proxy',
-  version: '1.0.0'
-}, { capabilities: {} });
-```
-
-**Verification Results:**
-- `runInteractiveSetup` (lines 439-639): **NEVER CALLED** - grep shows only definition
-- `import * as fs from 'fs'` (line 13): **UNUSED** - no `fs.` usage found
-- `import { spawn } from 'child_process'` (line 14): **UNUSED** - no `spawn(` calls
-- `homedir` (line 15): Only used in `runInteractiveSetup` (dead code)
-- `processPendingQueues` default `= 10`: Never used, all callers pass explicit args
-
----
-
-## Phase 1: Safe Deletions (Dead Code & Unused Imports)
-
-### 1.1 Delete `runInteractiveSetup` Function
-
-**What:** Delete lines 435-639 (~201 lines)
-**Why:** Function is defined but never called. Setup happens via `handleCursorCommand()`.
-**Evidence:** `grep -n "runInteractiveSetup" src/services/worker-service.ts` returns only definition
-
-**Pattern to follow:** N/A - straight deletion
-
-**Steps:**
-1. Read worker-service.ts lines 435-650
-2. Delete the entire function including section comment (lines 435-639)
-3. Run `npm run build` to verify no compile errors
-
-**Verification:**
-- `grep "runInteractiveSetup" src/` returns nothing
-- Build succeeds
-
-### 1.2 Remove Unused Imports
-
-**What:** Delete lines 13, 14, 17
-
-**Current (delete these):**
-```typescript
-import * as fs from 'fs';           // Line 13 - UNUSED
-import { spawn } from 'child_process';  // Line 14 - UNUSED
-import * as readline from 'readline';   // Line 17 - Only in dead code
-```
-
-**Keep:**
-```typescript
-import { homedir } from 'os';  // Line 15 - DELETE (only in dead code)
-import { existsSync, writeFileSync, readFileSync, mkdirSync } from 'fs';  // Line 16 - CHECK USAGE
-```
-
-**Steps:**
-1. After deleting `runInteractiveSetup`, grep for remaining usages:
-   - `grep "homedir" src/services/worker-service.ts`
-   - `grep "readline" src/services/worker-service.ts`
-   - `grep "detectClaudeCode\|findCursorHooksDir\|installCursorHooks\|configureCursorMcp" src/services/worker-service.ts`
-2. Delete imports with zero usages
-3. Run `npm run build`
-
-**Verification:**
-- No TypeScript unused import warnings
-- Build succeeds
-
-### 1.3 Clean Up Cursor Integration Imports
-
-After deleting `runInteractiveSetup`, some CursorHooksInstaller imports become unused:
-- `detectClaudeCode` - only in runInteractiveSetup
-- `findCursorHooksDir` - only in runInteractiveSetup
-- `installCursorHooks` - only in runInteractiveSetup
-- `configureCursorMcp` - only in runInteractiveSetup
-
-**Steps:**
-1. Grep each import after dead code removal
-2. Remove any that are now unused
-3. Keep `updateCursorContextForProject` (re-exported) and `handleCursorCommand` (used in main)
-
-**Verification:**
-- `grep "detectClaudeCode\|findCursorHooksDir\|installCursorHooks\|configureCursorMcp" src/services/worker-service.ts` returns nothing
-- Build succeeds
-
----
-
-## Phase 2: Low-Risk Simplifications
-
-### 2.1 Remove Unused Default Parameter
-
-**What:** Line 350 - `async processPendingQueues(sessionLimit: number = 10)`
-**Why:** Default never used. All callers pass explicit args (50 in startup, dynamic in HTTP)
-
-**Change from:**
-```typescript
-async processPendingQueues(sessionLimit: number = 10): Promise<{...}>
-```
-
-**Change to:**
-```typescript
-async processPendingQueues(sessionLimit: number): Promise<{...}>
-```
-
-**Verification:**
-- Build succeeds
-- All call sites provide explicit values
-
-### 2.2 Simplify onRestart Callback
-
-**Location:** Lines 395-396 (approximate, find exact)
-**Issue:** `onShutdown` and `onRestart` both call `this.shutdown()`
-
-**Find pattern:**
-```typescript
-onShutdown: () => this.shutdown(),
-onRestart: () => this.shutdown()
-```
-
-**Options:**
-1. **Keep as-is** if restart semantically differs from shutdown (future-proofing)
-2. **Add comment** explaining intentional parity
-3. **Remove onRestart** if never used differently
-
-**Investigation needed:** Grep for `onRestart` usage in Server.ts to understand contract
-
-**Steps:**
-1. Grep `onRestart` in `src/services/server/`
-2. If Server.ts treats them identically, add clarifying comment
-3. If different, document why both map to shutdown
-
-### 2.3 Fix Over-Commented Lines (Sample Only)
-
-**Strategy:** Do NOT strip all comments. Only remove comments that describe obvious code.
-
-**Anti-pattern (remove):**
-```typescript
-// WHAT: Imports centralized logging utility with structured output
-// WHY: All worker logs go through this for consistent formatting
-import { logger } from '../utils/logger.js';
-```
-
-**Pattern to follow:** Remove WHAT/WHY on simple imports. Keep architectural comments.
-
-**Scope:** Sample 5-10 obvious comment removals to demonstrate approach, not exhaustive
-
----
-
-## Phase 3: Medium-Risk Improvements
-
-### 3.1 Simplify Signal Handler Pattern
-
-**Current (worker-service.ts:180-192 + ProcessManager.ts:294-317):**
-```typescript
-// 3-hop indirection with mutable reference
-const shutdownRef = { value: this.isShuttingDown };
-const handler = createSignalHandler(() => this.shutdown(), shutdownRef);
-process.on('SIGTERM', () => {
-  this.isShuttingDown = shutdownRef.value;  // Sync back
-  handler('SIGTERM');
-});
-```
-
-**Simplified approach:**
-```typescript
-private registerSignalHandlers(): void {
-  const handler = async (signal: string) => {
-    if (this.isShuttingDown) {
-      logger.warn('SYSTEM', `Received ${signal} but shutdown already in progress`);
-      return;
-    }
-    this.isShuttingDown = true;
-    logger.info('SYSTEM', `Received ${signal}, shutting down...`);
-    try {
-      await this.shutdown();
-      process.exit(0);
-    } catch (error) {
-      logger.error('SYSTEM', 'Error during shutdown', {}, error as Error);
-      process.exit(0);
-    }
-  };
-
-  process.on('SIGTERM', () => handler('SIGTERM'));
-  process.on('SIGINT', () => handler('SIGINT'));
-}
-```
-
-**Decision needed:** Does `createSignalHandler` serve other callers? If yes, keep factory but simplify worker usage.
-
-**Steps:**
-1. Grep `createSignalHandler` usage across codebase
-2. If only worker-service uses it, inline and simplify
-3. If shared, simplify worker's usage while keeping factory
-
-### 3.2 Unify Dual Initialization Tracking
-
-**Current (lines 111, 129-130):**
-```typescript
-private initializationCompleteFlag: boolean = false;
-private initializationComplete: Promise<void>;
-```
-
-**Recommendation:** Keep both but add clarifying comments:
-- Promise: For async waiters (HTTP handlers)
-- Flag: For sync checks (status endpoints)
-
-**Alternative:** Use Promise with inspection pattern:
-```typescript
-private initializationComplete = false;
-private initializationPromise: Promise<void>;
-// Flag derived from promise state via finally() callback
-```
-
-**Steps:**
-1. Add documentation comment explaining dual tracking purpose
-2. Consider if flag can be derived from promise state instead
-
-### 3.3 Reduce 5-Minute Timeout
-
-**Location:** Lines 464-478 (approximate)
-**Current:** `const timeoutMs = 300000; // 5 minutes`
-**Recommendation:** Reduce to 30-60 seconds for HTTP handler, keep 5min for MCP init
-
-**Caution:** MCP initialization can legitimately be slow (ChromaDB, model loading). May need different timeouts per use case.
-
-**Steps:**
-1. Find exact line for context inject timeout
-2. Verify this is separate from MCP init timeout
-3. Reduce HTTP handler timeout to 30-60 seconds
-4. Keep MCP init timeout at 5 minutes
-
----
-
-## Phase 4: Deferred / Low Priority
-
-These items are noted but NOT part of this cleanup:
-
-| Issue | Reason to Defer |
-|-------|-----------------|
-| Exit code 0 always | Documented Windows Terminal workaround - intentional |
-| Re-export for circular import | Works correctly, architectural fix is separate work |
-| Fallback agent verification | Behavioral change, needs feature design |
-| MCP version hardcoding | Low impact, separate version management issue |
-| Empty capabilities | Documentation issue only |
-| Unsafe `as Error` casts | Common TS pattern, low risk |
-
----
-
-## Phase 5: Verification
-
-### 5.1 Build Verification
-```bash
-npm run build
-```
-Expected: No errors
-
-### 5.2 Test Suite
-```bash
-npm test
-```
-Expected: All tests pass
-
-### 5.3 Grep for Anti-patterns
-```bash
-# Verify dead code removed
-grep -r "runInteractiveSetup" src/
-
-# Verify unused imports removed
-grep "import \* as fs from 'fs'" src/services/worker-service.ts
-grep "import { spawn }" src/services/worker-service.ts
-```
-Expected: No matches
-
-### 5.4 Runtime Check
-```bash
-npm run build-and-sync
-# Start worker and verify basic operation
-```
-
----
-
-## Summary
-
-| Phase | Items | Estimated Reduction |
-|-------|-------|---------------------|
-| Phase 1 | Dead code + unused imports | ~210 lines |
-| Phase 2 | Low-risk simplifications | ~5 lines + clarity |
-| Phase 3 | Medium-risk improvements | ~30 lines |
-| Total | | ~245 lines (~30% reduction) |
-
-**Execution Order:** Phase 1 → Phase 2 → Phase 3 → Phase 5 (verification after each)

.claude/plans/fix-claudemd-worktree-bug.md

@@ -1,516 +0,0 @@
-# Fix CLAUDE.md Worktree Bug - Implementation Plan
-
-## Problem Statement
-
-CLAUDE.md files are being written to the wrong directory when using git worktrees. The worker service writes files relative to its own `process.cwd()` instead of the project's working directory (`cwd`) from the observation.
-
-**Reproduction scenario:**
-1. Start Claude Code in `budapest` worktree → worker starts with `cwd=budapest`
-2. Run Claude Code in `~/Scripts/claude-mem/` (main repo)
-3. Observations created with relative file paths (e.g., `src/utils/foo.ts`)
-4. `updateFolderClaudeMdFiles` writes to `budapest/src/utils/CLAUDE.md` instead of main repo
-
-## Root Cause Analysis
-
-The `cwd` (project root path) IS captured and stored:
-- `SessionRoutes.ts:309,403` - receives `cwd` from hooks
-- `PendingMessageStore.ts:70` - stores `cwd` in database
-- `SDKAgent.ts:295` - passes `cwd` to prompt builder
-
-But `cwd` is NOT passed to file writing:
-- `ResponseProcessor.ts:222-225` - calls `updateFolderClaudeMdFiles(allFilePaths, session.project, port)` without `cwd`
-- `claude-md-utils.ts:219` - uses `path.dirname(filePath)` which produces relative paths
-- Relative paths resolve against worker's `process.cwd()`, not project root
-
----
-
-## Phase 0: Documentation & API Inventory
-
-### Allowed APIs (from codebase analysis)
-
-**File: `src/utils/claude-md-utils.ts`**
-```typescript
-export async function updateFolderClaudeMdFiles(
-  filePaths: string[],
-  project: string,
-  port: number
-): Promise<void>
-```
-
-**File: `src/sdk/parser.ts`**
-```typescript
-export interface ParsedObservation {
-  type: string;
-  title: string | null;
-  subtitle: string | null;
-  facts: string[];
-  narrative: string | null;
-  concepts: string[];
-  files_read: string[];
-  files_modified: string[];
-  // NOTE: Does NOT include cwd
-}
-```
-
-**File: `src/services/worker-types.ts`**
-```typescript
-export interface PendingMessage {
-  type: 'observation' | 'summarize';
-  tool_name?: string;
-  tool_input?: unknown;
-  tool_response?: unknown;
-  prompt_number?: number;
-  cwd?: string;  // <-- Source of project root
-  last_assistant_message?: string;
-}
-```
-
-**File: `src/shared/paths.ts`** - Path utilities
-```typescript
-import path from 'path';
-// Standard pattern: path.join(baseDir, relativePath)
-```
-
-### Anti-Patterns to Avoid
-
-1. **DO NOT** add `cwd` to `ParsedObservation` - it comes from message, not agent response
-2. **DO NOT** use `process.cwd()` for project-specific paths
-3. **DO NOT** assume file paths are absolute - they are relative from agent response
-4. **DO NOT** modify the parser - file paths come from agent XML output
-
----
-
-## Phase 1: Add `projectRoot` Parameter to `updateFolderClaudeMdFiles`
-
-### What to implement
-
-Modify the function signature to accept an optional `projectRoot` parameter for resolving relative paths to absolute paths.
-
-### Files to modify
-
-**File: `src/utils/claude-md-utils.ts`**
-
-**Location: Lines 206-210 (function signature)**
-
-Current:
-```typescript
-export async function updateFolderClaudeMdFiles(
-  filePaths: string[],
-  project: string,
-  port: number
-): Promise<void>
-```
-
-New:
-```typescript
-export async function updateFolderClaudeMdFiles(
-  filePaths: string[],
-  project: string,
-  port: number,
-  projectRoot?: string
-): Promise<void>
-```
-
-**Location: Lines 215-228 (folder extraction logic)**
-
-Current:
-```typescript
-const folderPaths = new Set<string>();
-for (const filePath of filePaths) {
-  if (!filePath || filePath === '') continue;
-  const folderPath = path.dirname(filePath);
-  if (folderPath && folderPath !== '.' && folderPath !== '/') {
-    if (isProjectRoot(folderPath)) {
-      logger.debug('FOLDER_INDEX', 'Skipping project root CLAUDE.md', { folderPath });
-      continue;
-    }
-    folderPaths.add(folderPath);
-  }
-}
-```
-
-New:
-```typescript
-const folderPaths = new Set<string>();
-for (const filePath of filePaths) {
-  if (!filePath || filePath === '') continue;
-
-  // Resolve relative paths to absolute using projectRoot
-  let absoluteFilePath = filePath;
-  if (projectRoot && !path.isAbsolute(filePath)) {
-    absoluteFilePath = path.join(projectRoot, filePath);
-  }
-
-  const folderPath = path.dirname(absoluteFilePath);
-  if (folderPath && folderPath !== '.' && folderPath !== '/') {
-    if (isProjectRoot(folderPath)) {
-      logger.debug('FOLDER_INDEX', 'Skipping project root CLAUDE.md', { folderPath });
-      continue;
-    }
-    folderPaths.add(folderPath);
-  }
-}
-```
-
-### Documentation references
-
-- Pattern for `path.isAbsolute()`: Standard Node.js path module
-- Pattern for `path.join(base, relative)`: Used throughout `src/shared/paths.ts`
-
-### Verification checklist
-
-1. [ ] `grep -n "updateFolderClaudeMdFiles" src/utils/claude-md-utils.ts` shows new signature
-2. [ ] `grep -n "path.isAbsolute" src/utils/claude-md-utils.ts` confirms new check added
-3. [ ] `grep -n "projectRoot" src/utils/claude-md-utils.ts` shows parameter usage
-4. [ ] Existing callers still compile (optional param is backward compatible)
-
-### Anti-pattern guards
-
-- **DO NOT** make `projectRoot` required - breaks existing callers
-- **DO NOT** use `process.cwd()` as default - defeats purpose of fix
-- **DO NOT** modify the API endpoint format - path resolution is caller's responsibility
-
----
-
-## Phase 2: Pass `cwd` from Message to `updateFolderClaudeMdFiles`
-
-### What to implement
-
-Extract `cwd` from the original messages being processed and pass it to `updateFolderClaudeMdFiles`.
-
-### Challenge
-
-The `syncAndBroadcastObservations` function receives `ParsedObservation[]` which does NOT include `cwd`. The `cwd` is in the original `PendingMessage` but is consumed during prompt generation.
-
-### Solution
-
-Add `projectRoot` parameter to `syncAndBroadcastObservations` and `processAgentResponse`, sourced from `session` or passed through from message processing.
-
-### Files to modify
-
-**File: `src/services/worker/agents/ResponseProcessor.ts`**
-
-**Step 1: Update `processAgentResponse` signature (lines 46-55)**
-
-Current:
-```typescript
-export async function processAgentResponse(
-  text: string,
-  session: ActiveSession,
-  dbManager: DatabaseManager,
-  sessionManager: SessionManager,
-  worker: WorkerRef | undefined,
-  discoveryTokens: number,
-  originalTimestamp: number | null,
-  agentName: string
-): Promise<void>
-```
-
-New:
-```typescript
-export async function processAgentResponse(
-  text: string,
-  session: ActiveSession,
-  dbManager: DatabaseManager,
-  sessionManager: SessionManager,
-  worker: WorkerRef | undefined,
-  discoveryTokens: number,
-  originalTimestamp: number | null,
-  agentName: string,
-  projectRoot?: string
-): Promise<void>
-```
-
-**Step 2: Pass `projectRoot` to `syncAndBroadcastObservations` (line 101-109)**
-
-Current:
-```typescript
-await syncAndBroadcastObservations(
-  observations,
-  result,
-  session,
-  dbManager,
-  worker,
-  discoveryTokens,
-  agentName
-);
-```
-
-New:
-```typescript
-await syncAndBroadcastObservations(
-  observations,
-  result,
-  session,
-  dbManager,
-  worker,
-  discoveryTokens,
-  agentName,
-  projectRoot
-);
-```
-
-**Step 3: Update `syncAndBroadcastObservations` signature (lines 153-161)**
-
-Current:
-```typescript
-async function syncAndBroadcastObservations(
-  observations: ParsedObservation[],
-  result: StorageResult,
-  session: ActiveSession,
-  dbManager: DatabaseManager,
-  worker: WorkerRef | undefined,
-  discoveryTokens: number,
-  agentName: string
-): Promise<void>
-```
-
-New:
-```typescript
-async function syncAndBroadcastObservations(
-  observations: ParsedObservation[],
-  result: StorageResult,
-  session: ActiveSession,
-  dbManager: DatabaseManager,
-  worker: WorkerRef | undefined,
-  discoveryTokens: number,
-  agentName: string,
-  projectRoot?: string
-): Promise<void>
-```
-
-**Step 4: Update `updateFolderClaudeMdFiles` call (lines 222-229)**
-
-Current:
-```typescript
-if (allFilePaths.length > 0) {
-  updateFolderClaudeMdFiles(
-    allFilePaths,
-    session.project,
-    getWorkerPort()
-  ).catch(error => {
-    logger.warn('FOLDER_INDEX', 'CLAUDE.md update failed (non-critical)', { project: session.project }, error as Error);
-  });
-}
-```
-
-New:
-```typescript
-if (allFilePaths.length > 0) {
-  updateFolderClaudeMdFiles(
-    allFilePaths,
-    session.project,
-    getWorkerPort(),
-    projectRoot
-  ).catch(error => {
-    logger.warn('FOLDER_INDEX', 'CLAUDE.md update failed (non-critical)', { project: session.project }, error as Error);
-  });
-}
-```
-
-### Verification checklist
-
-1. [ ] `grep -n "projectRoot" src/services/worker/agents/ResponseProcessor.ts` shows parameter throughout
-2. [ ] `grep -n "processAgentResponse" src/services/worker/*.ts` to find all callers
-3. [ ] TypeScript compiles without errors
-
-### Anti-pattern guards
-
-- **DO NOT** extract `cwd` from `ParsedObservation` - it doesn't have one
-- **DO NOT** store `cwd` on session globally - messages may come from different cwds (edge case)
-
----
-
-## Phase 3: Update Agent Callers to Pass `cwd`
-
-### What to implement
-
-Update SDKAgent, GeminiAgent, and OpenRouterAgent to pass `message.cwd` to `processAgentResponse`.
-
-### Files to modify
-
-**File: `src/services/worker/SDKAgent.ts`**
-
-Find the `processAgentResponse` call and add the `projectRoot` parameter from `message.cwd`.
-
-**Pattern to follow (from SDKAgent.ts:289-296):**
-```typescript
-const obsPrompt = buildObservationPrompt({
-  id: 0,
-  tool_name: message.tool_name!,
-  tool_input: JSON.stringify(message.tool_input),
-  tool_output: JSON.stringify(message.tool_response),
-  created_at_epoch: Date.now(),
-  cwd: message.cwd  // <-- This is available
-});
-```
-
-**Challenge:** `processAgentResponse` is called after the SDK response, not in the message loop. Need to track `lastCwd` from messages.
-
-**Solution:** Store `lastCwd` from messages being processed and pass to `processAgentResponse`.
-
-**File: `src/services/worker/GeminiAgent.ts`** - Same pattern
-**File: `src/services/worker/OpenRouterAgent.ts`** - Same pattern
-
-### Implementation pattern for each agent
-
-Add tracking variable:
-```typescript
-let lastCwd: string | undefined;
-```
-
-In message loop, capture cwd:
-```typescript
-if (message.cwd) {
-  lastCwd = message.cwd;
-}
-```
-
-In `processAgentResponse` call:
-```typescript
-await processAgentResponse(
-  responseText,
-  session,
-  this.dbManager,
-  this.sessionManager,
-  worker,
-  discoveryTokens,
-  originalTimestamp,
-  'SDK',  // or 'Gemini' or 'OpenRouter'
-  lastCwd
-);
-```
-
-### Verification checklist
-
-1. [ ] `grep -n "lastCwd" src/services/worker/SDKAgent.ts` shows tracking
-2. [ ] `grep -n "lastCwd" src/services/worker/GeminiAgent.ts` shows tracking
-3. [ ] `grep -n "lastCwd" src/services/worker/OpenRouterAgent.ts` shows tracking
-4. [ ] `grep -n "processAgentResponse.*lastCwd" src/services/worker/` shows all calls updated
-
-### Anti-pattern guards
-
-- **DO NOT** use `session.cwd` - sessions can have messages from multiple cwds
-- **DO NOT** default to `process.cwd()` - defeats the fix
-
----
-
-## Phase 4: Update Tests
-
-### What to implement
-
-Update existing tests and add new tests for the `projectRoot` functionality.
-
-### Files to modify
-
-**File: `tests/utils/claude-md-utils.test.ts`**
-
-Add test cases for:
-1. Relative paths with `projectRoot` resolve correctly
-2. Absolute paths ignore `projectRoot`
-3. Missing `projectRoot` maintains backward compatibility
-
-### Test pattern to copy
-
-From `tests/utils/claude-md-utils.test.ts:245-266` (folder deduplication test):
-```typescript
-it('should deduplicate folders from multiple files', async () => {
-  mockFetch.mockResolvedValue({
-    ok: true,
-    json: () => Promise.resolve({ content: [{ text: mockApiResponse }] })
-  });
-
-  await updateFolderClaudeMdFiles(
-    ['/project/src/utils/file1.ts', '/project/src/utils/file2.ts'],
-    'test-project',
-    37777
-  );
-
-  // Should only call API once for the deduplicated folder
-  expect(mockFetch).toHaveBeenCalledTimes(1);
-});
-```
-
-### New test to add
-
-```typescript
-it('should resolve relative paths using projectRoot', async () => {
-  mockFetch.mockResolvedValue({
-    ok: true,
-    json: () => Promise.resolve({ content: [{ text: mockApiResponse }] })
-  });
-
-  await updateFolderClaudeMdFiles(
-    ['src/utils/file.ts'],  // relative path
-    'test-project',
-    37777,
-    '/home/user/my-project'  // projectRoot
-  );
-
-  // Should write to absolute path /home/user/my-project/src/utils/CLAUDE.md
-  expect(mockWriteClaudeMd).toHaveBeenCalledWith(
-    '/home/user/my-project/src/utils',
-    expect.any(String)
-  );
-});
-```
-
-### Verification checklist
-
-1. [ ] `bun test tests/utils/claude-md-utils.test.ts` passes
-2. [ ] New test case for `projectRoot` exists and passes
-
----
-
-## Phase 5: Final Verification
-
-### Verification commands
-
-```bash
-# 1. Confirm new parameter exists
-grep -n "projectRoot" src/utils/claude-md-utils.ts
-grep -n "projectRoot" src/services/worker/agents/ResponseProcessor.ts
-grep -n "lastCwd" src/services/worker/SDKAgent.ts
-
-# 2. Confirm path.isAbsolute check added
-grep -n "path.isAbsolute" src/utils/claude-md-utils.ts
-
-# 3. Confirm all agents updated
-grep -n "processAgentResponse.*lastCwd" src/services/worker/*.ts
-
-# 4. Run tests
-bun test tests/utils/claude-md-utils.test.ts
-
-# 5. Build and verify no TypeScript errors
-npm run build
-```
-
-### Anti-pattern grep checks
-
-```bash
-# Should NOT find process.cwd() in updateFolderClaudeMdFiles path logic
-grep -n "process.cwd" src/utils/claude-md-utils.ts
-
-# Should NOT find cwd in ParsedObservation interface
-grep -A 10 "interface ParsedObservation" src/sdk/parser.ts | grep cwd
-```
-
-### Manual testing
-
-1. Start worker in one directory
-2. Run Claude Code in a different directory (worktree)
-3. Make a code change that creates an observation
-4. Verify CLAUDE.md is written to the correct project directory
-
----
-
-## Summary of Changes
-
-| File | Change |
-|------|--------|
-| `src/utils/claude-md-utils.ts` | Add `projectRoot` param, resolve relative paths |
-| `src/services/worker/agents/ResponseProcessor.ts` | Pass `projectRoot` through call chain |
-| `src/services/worker/SDKAgent.ts` | Track `lastCwd`, pass to `processAgentResponse` |
-| `src/services/worker/GeminiAgent.ts` | Track `lastCwd`, pass to `processAgentResponse` |
-| `src/services/worker/OpenRouterAgent.ts` | Track `lastCwd`, pass to `processAgentResponse` |
-| `tests/utils/claude-md-utils.test.ts` | Add tests for `projectRoot` behavior |

.claude/plans/fix-empty-claude-md-files.md

@@ -1,266 +0,0 @@
-# Plan: Fix Empty CLAUDE.md File Generation
-
-## Problem Statement
-
-Currently the CLAUDE.md generator creates files with wasteful content:
-1. **Empty files with "No recent activity"** - Files are created even when there are zero observations for a folder
-2. **Redundant HTML comment** - "<!-- This section is auto-generated by claude-mem. Edit content outside the tags. -->" is unnecessary since the `<claude-mem-context>` tag already conveys this information
-
-These issues create noisy, wasteful context that loads automatically and provides no value.
-
-## Phase 0: Documentation Discovery
-
-### Allowed APIs (from code analysis)
-- `formatTimelineForClaudeMd(timelineText: string): string` - src/utils/claude-md-utils.ts:139
-- `formatObservationsForClaudeMd(observations, folderPath): string` - scripts/regenerate-claude-md.ts:238
-- `writeClaudeMdToFolder(folderPath, newContent): void` - src/utils/claude-md-utils.ts:94
-- `updateFolderClaudeMdFiles(filePaths, project, port, projectRoot): Promise<void>` - src/utils/claude-md-utils.ts:257
-- `replaceTaggedContent(existingContent, newContent): string` - src/utils/claude-md-utils.ts:64
-
-### Key Locations
-| File | Lines | Purpose |
-|------|-------|---------|
-| `src/utils/claude-md-utils.ts` | 139-235 | Main formatting function |
-| `src/utils/claude-md-utils.ts` | 143 | HTML comment generation |
-| `src/utils/claude-md-utils.ts` | 209-211 | "No recent activity" handling |
-| `src/utils/claude-md-utils.ts` | 322-323 | Write decision point |
-| `scripts/regenerate-claude-md.ts` | 238-286 | Regeneration script formatting |
-| `scripts/regenerate-claude-md.ts` | 242 | HTML comment generation (duplicate) |
-| `scripts/regenerate-claude-md.ts` | 245-247 | "No recent activity" handling |
-| `scripts/regenerate-claude-md.ts` | 452-453 | Write decision point |
-| `tests/utils/claude-md-utils.test.ts` | 96-109 | Tests for "No recent activity" behavior |
-
-### Anti-patterns to avoid
-- Do NOT add new configuration options for this behavior - just fix it
-- Do NOT add logging for skipped files (unnecessary noise)
-
----
-
-## Phase 1: Modify formatTimelineForClaudeMd to Return Empty on No Observations
-
-### Task 1.1: Update formatTimelineForClaudeMd return behavior
-**File:** `src/utils/claude-md-utils.ts`
-**Lines:** 139-235
-
-**Changes:**
-1. Remove HTML comment line at line 143
-2. Change the empty observations case (lines 209-211) to return an empty string instead of "No recent activity"
-
-**Before (lines 141-144):**
-```typescript
-lines.push('# Recent Activity');
-lines.push('');
-lines.push('<!-- This section is auto-generated by claude-mem. Edit content outside the tags. -->');
-lines.push('');
-```
-
-**After:**
-```typescript
-lines.push('# Recent Activity');
-lines.push('');
-```
-
-**Before (lines 209-212):**
-```typescript
-if (observations.length === 0) {
-  lines.push('*No recent activity*');
-  return lines.join('\n');
-}
-```
-
-**After:**
-```typescript
-if (observations.length === 0) {
-  return '';
-}
-```
-
-### Verification
-- Run `bun test tests/utils/claude-md-utils.test.ts`
-- Tests at lines 96-109 will FAIL (expected - they test for "No recent activity")
-- Update tests to expect empty string for empty input
-
----
-
-## Phase 2: Update updateFolderClaudeMdFiles to Skip Empty Content
-
-### Task 2.1: Add empty content check before writing
-**File:** `src/utils/claude-md-utils.ts`
-**Lines:** 322-323
-
-**Changes:**
-After formatting, check if result is empty and skip writing if so.
-
-**Before (lines 321-325):**
-```typescript
-const formatted = formatTimelineForClaudeMd(result.content[0].text);
-writeClaudeMdToFolder(folderPath, formatted);
-
-logger.debug('FOLDER_INDEX', 'Updated CLAUDE.md', { folderPath });
-```
-
-**After:**
-```typescript
-const formatted = formatTimelineForClaudeMd(result.content[0].text);
-if (!formatted) {
-  logger.debug('FOLDER_INDEX', 'No observations for folder, skipping', { folderPath });
-  continue;
-}
-writeClaudeMdToFolder(folderPath, formatted);
-
-logger.debug('FOLDER_INDEX', 'Updated CLAUDE.md', { folderPath });
-```
-
-### Verification
-- Grep for files containing "No recent activity": should find none after running
-
----
-
-## Phase 3: Update Regeneration Script
-
-### Task 3.1: Remove HTML comment from formatObservationsForClaudeMd
-**File:** `scripts/regenerate-claude-md.ts`
-**Lines:** 238-286
-
-**Changes:**
-1. Remove HTML comment line at line 242
-2. Change empty observations case (lines 245-247) to return empty string
-
-**Before (lines 240-244):**
-```typescript
-lines.push('# Recent Activity');
-lines.push('');
-lines.push('<!-- This section is auto-generated by claude-mem. Edit content outside the tags. -->');
-lines.push('');
-```
-
-**After:**
-```typescript
-lines.push('# Recent Activity');
-lines.push('');
-```
-
-**Before (lines 245-248):**
-```typescript
-if (observations.length === 0) {
-  lines.push('*No recent activity*');
-  return lines.join('\n');
-}
-```
-
-**After:**
-```typescript
-if (observations.length === 0) {
-  return '';
-}
-```
-
-### Task 3.2: Update regenerateFolder to handle empty formatted content
-**File:** `scripts/regenerate-claude-md.ts`
-**Lines:** 432-459
-
-The script already skips folders with no observations (lines 443-444), so this change is already compatible. The `formatObservationsForClaudeMd` returning empty string doesn't change behavior since observations are checked before calling it.
-
-### Verification
-- Run `bun scripts/regenerate-claude-md.ts --dry-run` in the project
-- Should NOT show any folders with 0 observations
-
----
-
-## Phase 4: Update Tests
-
-### Task 4.1: Update tests for new empty behavior
-**File:** `tests/utils/claude-md-utils.test.ts`
-**Lines:** 96-109
-
-**Changes:**
-Update the two tests that expect "No recent activity" to expect empty string instead.
-
-**Before (lines 96-101):**
-```typescript
-it('should return "No recent activity" for empty input', () => {
-  const result = formatTimelineForClaudeMd('');
-
-  expect(result).toContain('# Recent Activity');
-  expect(result).toContain('*No recent activity*');
-});
-```
-
-**After:**
-```typescript
-it('should return empty string for empty input', () => {
-  const result = formatTimelineForClaudeMd('');
-
-  expect(result).toBe('');
-});
-```
-
-**Before (lines 103-109):**
-```typescript
-it('should return "No recent activity" when no table rows exist', () => {
-  const input = 'Just some plain text without table rows';
-
-  const result = formatTimelineForClaudeMd(input);
-
-  expect(result).toContain('*No recent activity*');
-});
-```
-
-**After:**
-```typescript
-it('should return empty string when no table rows exist', () => {
-  const input = 'Just some plain text without table rows';
-
-  const result = formatTimelineForClaudeMd(input);
-
-  expect(result).toBe('');
-});
-```
-
-### Task 4.2: Remove HTML comment assertions from any other tests
-Search for tests that assert on "auto-generated" comment and update accordingly.
-
-### Verification
-- Run full test suite: `bun test`
-- All tests should pass
-
----
-
-## Phase 5: Cleanup Existing Empty Files
-
-### Task 5.1: Run cleanup to remove existing empty CLAUDE.md files
-**Command:**
-```bash
-bun scripts/regenerate-claude-md.ts --clean
-```
-
-This will:
-- Find all CLAUDE.md files with `<claude-mem-context>` tags
-- Strip the tagged section
-- Delete files that become empty after stripping
-- Preserve files that have user content outside the tags
-
-### Verification
-- `grep -r "No recent activity" . --include="CLAUDE.md"` should return no results
-- `grep -r "auto-generated by claude-mem" . --include="CLAUDE.md"` should return no results
-
----
-
-## Summary of Changes
-
-| File | Change |
-|------|--------|
-| `src/utils/claude-md-utils.ts:143` | Remove HTML comment line |
-| `src/utils/claude-md-utils.ts:209-211` | Return empty string instead of "No recent activity" |
-| `src/utils/claude-md-utils.ts:322` | Skip writing if formatted content is empty |
-| `scripts/regenerate-claude-md.ts:242` | Remove HTML comment line |
-| `scripts/regenerate-claude-md.ts:245-247` | Return empty string instead of "No recent activity" |
-| `tests/utils/claude-md-utils.test.ts:96-109` | Update tests to expect empty string |
-
-## Final Verification Checklist
-- [ ] `bun test` passes
-- [ ] No "No recent activity" CLAUDE.md files exist
-- [ ] No "auto-generated" comments in CLAUDE.md files
-- [ ] Build succeeds: `npm run build-and-sync`
-- [ ] New observations correctly generate CLAUDE.md files with content
-- [ ] Folders without observations get no CLAUDE.md file created

.claude/plans/fix-stale-session-resume-crash.md

@@ -1,252 +0,0 @@
-# Plan: Fix Stale Session Resume Crash
-
-## Problem Summary
-
-The worker crashes repeatedly with "Claude Code process exited with code 1" when attempting to resume into a stale/non-existent SDK session.
-
-**Root Cause:** In `SDKAgent.ts:94`, the resume parameter is passed whenever `memorySessionId` exists in the database, regardless of whether this is an INIT prompt or CONTINUATION prompt. When a worker restarts or re-initializes a session, it loads a stale `memorySessionId` from a previous SDK session and tries to resume into a session that no longer exists in Claude's context.
-
-**Evidence from logs:**
-```
-[17:30:21.773] Starting SDK query {
-  hasRealMemorySessionId=true,           ← DB has old memorySessionId
-  resume_parameter=5439891b-...,         ← Trying to resume with it
-  lastPromptNumber=1                     ← But this is a NEW SDK session!
-}
-[17:30:24.450] Generator failed {error=Claude Code process exited with code 1}
-```
-
----
-
-## Phase 0: Documentation Discovery (COMPLETED)
-
-### Allowed APIs (from subagent research)
-
-**V1 SDK API (currently used):**
-```typescript
-// From @anthropic-ai/claude-agent-sdk
-function query(options: {
-  prompt: string | AsyncIterable<SDKUserMessage>;
-  options: {
-    model: string;
-    resume?: string;  // SESSION ID - only use for CONTINUATION
-    disallowedTools?: string[];
-    abortController?: AbortController;
-    pathToClaudeCodeExecutable?: string;
-  }
-}): AsyncIterable<SDKMessage>
-```
-
-**Resume Parameter Rules (from docs/context/agent-sdk-v2-preview.md and SESSION_ID_ARCHITECTURE.md):**
-- `resume` should only be used when continuing an existing SDK conversation
-- For INIT prompts (first prompt in a fresh SDK session), no resume parameter should be passed
-- Session ID is captured from first SDK message and stored for subsequent prompts
-
-### Anti-Patterns to Avoid
-- Passing `resume` parameter with INIT prompts (causes crash)
-- Using `contentSessionId` for resume (contaminates user session)
-- Assuming memorySessionId validity without checking prompt context
-
----
-
-## Phase 1: Fix the Resume Parameter Logic
-
-### What to Implement
-
-Modify `src/services/worker/SDKAgent.ts` line 94 to check BOTH conditions:
-1. `hasRealMemorySessionId` - memorySessionId exists and is non-null
-2. `session.lastPromptNumber > 1` - this is a CONTINUATION, not an INIT prompt
-
-### Current Code (line 89-99):
-```typescript
-const queryResult = query({
-  prompt: messageGenerator,
-  options: {
-    model: modelId,
-    // Resume with captured memorySessionId (null on first prompt, real ID on subsequent)
-    ...(hasRealMemorySessionId && { resume: session.memorySessionId }),
-    disallowedTools,
-    abortController: session.abortController,
-    pathToClaudeCodeExecutable: claudePath
-  }
-});
-```
-
-### Fixed Code:
-```typescript
-const queryResult = query({
-  prompt: messageGenerator,
-  options: {
-    model: modelId,
-    // Only resume if BOTH: (1) we have a memorySessionId AND (2) this isn't the first prompt
-    // On worker restart, memorySessionId may exist from a previous SDK session but we
-    // need to start fresh since the SDK context was lost
-    ...(hasRealMemorySessionId && session.lastPromptNumber > 1 && { resume: session.memorySessionId }),
-    disallowedTools,
-    abortController: session.abortController,
-    pathToClaudeCodeExecutable: claudePath
-  }
-});
-```
-
-### Also Update the Comment at Line 66-68:
-```typescript
-// CRITICAL: Only resume if:
-// 1. memorySessionId exists (was captured from a previous SDK response)
-// 2. lastPromptNumber > 1 (this is a continuation within the same SDK session)
-// On worker restart or crash recovery, memorySessionId may exist from a previous
-// SDK session but we must NOT resume because the SDK context was lost.
-// NEVER use contentSessionId for resume - that would inject messages into the user's transcript!
-```
-
-### Verification Checklist
-- [ ] `grep "hasRealMemorySessionId && session.lastPromptNumber > 1" src/services/worker/SDKAgent.ts` returns the fix
-- [ ] Build succeeds: `npm run build`
-- [ ] No TypeScript errors
-
----
-
-## Phase 2: Add Logging for Debugging
-
-### What to Implement
-
-Enhance the alignment log at line 81-85 to clearly indicate when resume is skipped due to INIT prompt:
-
-```typescript
-// Debug-level alignment logs for detailed tracing
-if (session.lastPromptNumber > 1) {
-  const willResume = hasRealMemorySessionId;
-  logger.debug('SDK', `[ALIGNMENT] Resume Decision | contentSessionId=${session.contentSessionId} | memorySessionId=${session.memorySessionId} | prompt#=${session.lastPromptNumber} | hasRealMemorySessionId=${hasRealMemorySessionId} | willResume=${willResume} | resumeWith=${willResume ? session.memorySessionId : 'NONE'}`);
-} else {
-  // INIT prompt - never resume even if memorySessionId exists (stale from previous session)
-  const hasStaleMemoryId = hasRealMemorySessionId;
-  logger.debug('SDK', `[ALIGNMENT] First Prompt (INIT) | contentSessionId=${session.contentSessionId} | prompt#=${session.lastPromptNumber} | hasStaleMemoryId=${hasStaleMemoryId} | action=START_FRESH | Will capture new memorySessionId from SDK response`);
-  if (hasStaleMemoryId) {
-    logger.warn('SDK', `Skipping resume for INIT prompt despite existing memorySessionId=${session.memorySessionId} - SDK context was lost (worker restart or crash recovery)`);
-  }
-}
-```
-
-### Verification Checklist
-- [ ] Build succeeds: `npm run build`
-- [ ] Log message appears when running with stale session scenario
-
----
-
-## Phase 3: Add Unit Tests
-
-### What to Implement
-
-Create tests in `tests/sdk-agent-resume.test.ts` following patterns from `tests/session_id_usage_validation.test.ts`:
-
-```typescript
-import { describe, it, expect, beforeEach, afterEach, mock } from 'bun:test';
-
-describe('SDKAgent Resume Parameter Logic', () => {
-  describe('hasRealMemorySessionId check', () => {
-    it('should NOT pass resume parameter when lastPromptNumber === 1 even if memorySessionId exists', () => {
-      // Scenario: Worker restart with stale memorySessionId
-      const session = {
-        memorySessionId: 'stale-session-id-from-previous-run',
-        lastPromptNumber: 1,  // INIT prompt
-      };
-
-      const hasRealMemorySessionId = !!session.memorySessionId;
-      const shouldResume = hasRealMemorySessionId && session.lastPromptNumber > 1;
-
-      expect(hasRealMemorySessionId).toBe(true);  // memorySessionId exists
-      expect(shouldResume).toBe(false);  // but should NOT resume
-    });
-
-    it('should pass resume parameter when lastPromptNumber > 1 AND memorySessionId exists', () => {
-      // Scenario: Normal continuation within same SDK session
-      const session = {
-        memorySessionId: 'valid-session-id',
-        lastPromptNumber: 2,  // CONTINUATION prompt
-      };
-
-      const hasRealMemorySessionId = !!session.memorySessionId;
-      const shouldResume = hasRealMemorySessionId && session.lastPromptNumber > 1;
-
-      expect(hasRealMemorySessionId).toBe(true);
-      expect(shouldResume).toBe(true);
-    });
-
-    it('should NOT pass resume parameter when memorySessionId is null', () => {
-      // Scenario: Fresh session, no captured ID yet
-      const session = {
-        memorySessionId: null,
-        lastPromptNumber: 1,
-      };
-
-      const hasRealMemorySessionId = !!session.memorySessionId;
-      const shouldResume = hasRealMemorySessionId && session.lastPromptNumber > 1;
-
-      expect(hasRealMemorySessionId).toBe(false);
-      expect(shouldResume).toBe(false);
-    });
-  });
-});
-```
-
-### Documentation Reference
-- Pattern: `tests/session_id_usage_validation.test.ts` lines 1-50 for test structure
-- Mock pattern: `tests/worker/agents/response-processor.test.ts` for session mocking
-
-### Verification Checklist
-- [ ] Tests pass: `bun test tests/sdk-agent-resume.test.ts`
-- [ ] Test file follows project conventions
-
----
-
-## Phase 4: Build and Deploy
-
-### What to Implement
-
-1. Build the plugin: `npm run build-and-sync`
-2. Verify worker restarts with fix applied
-
-### Verification Checklist
-- [ ] `npm run build-and-sync` succeeds
-- [ ] Worker health check passes: `curl http://localhost:37777/api/health`
-- [ ] No "Claude Code process exited with code 1" errors in logs after restart
-
----
-
-## Phase 5: Final Verification
-
-### Verification Commands
-
-```bash
-# 1. Verify fix is in place
-grep -n "hasRealMemorySessionId && session.lastPromptNumber > 1" src/services/worker/SDKAgent.ts
-
-# 2. Verify no crashes in recent logs
-tail -100 ~/.claude-mem/logs/claude-mem-$(date +%Y-%m-%d).log | grep -c "exited with code 1"
-
-# 3. Run tests
-bun test tests/sdk-agent-resume.test.ts
-
-# 4. Check for anti-patterns (should return 0 results)
-grep -n "hasRealMemorySessionId && { resume" src/services/worker/SDKAgent.ts
-```
-
-### Success Criteria
-- [ ] Fix in place at SDKAgent.ts:94
-- [ ] Zero "exited with code 1" errors related to stale resume
-- [ ] All tests pass
-- [ ] Worker stable for 10+ minutes without crash loop
-
----
-
-## Files to Modify
-
-1. `src/services/worker/SDKAgent.ts` - Fix resume logic (Phase 1 & 2)
-2. `tests/sdk-agent-resume.test.ts` - New test file (Phase 3)
-
-## Estimated Complexity
-
-- **Phase 1**: Low - Single line change with updated condition
-- **Phase 2**: Low - Enhanced logging
-- **Phase 3**: Medium - New test file following existing patterns
-- **Phase 4-5**: Low - Standard build/verify process

.claude/plans/folder-claude-md-generator.md

@@ -1,298 +0,0 @@
-# Folder CLAUDE.md Generator
-
-## CORE DIRECTIVE (NON-NEGOTIABLE)
-
-**EXTEND THE EXISTING CURSOR RULES TIMELINE GENERATION SYSTEM TO ALSO WRITE CLAUDE.MD FILES**
-
-- DO NOT create new services
-- DO NOT create new orchestrators
-- DO NOT create new HTTP routes
-- DO NOT create new database query functions
-- EXTEND existing functions to add folder-level output
-
----
-
-## Approved Directives (From Planning Conversation)
-
-### Trigger Mechanism
-- Observation save triggers folder CLAUDE.md regeneration **INLINE**
-- NO batching
-- NO debouncing
-- NO Set-based queuing
-- NO session-end hook
-- Synchronous: `observation.save()` → update folder CLAUDE.md files → done
-
-### Tag Strategy
-- Wrap ONLY auto-generated content with `<claude-mem-context>` tags
-- Everything outside tags is untouched (user's manual content preserved)
-- If tags are deleted, just regenerate them
-- NO backup system
-- NO manual content markers
-
-### Git Behavior
-- CLAUDE.md files SHOULD be committed (intentional)
-- `<claude-mem-context>` tag is searchable fingerprint for GitHub analytics
-- NO .gitignore for these files
-
-### Phasing
-- **Phase 1**: CLAUDE.md generation only (THIS PLAN)
-- **Phase 2**: IDE symlinks (FUTURE)
-
-### REJECTED
-- Cross-folder linking — NO
-- Semantic grouping — deferred enhancement only
-- Team sync — future phase
-
-### DEFERRED
-- Priority weighting by observation type
-- IDE-specific template refinements
-
----
-
-## Phase 0: Documentation Discovery (COMPLETED)
-
-### Existing APIs to USE (Not Rebuild)
-
-| Function | Location | Purpose |
-|----------|----------|---------|
-| `findByFile(filePath, options)` | `src/services/sqlite/SessionSearch.ts:342` | Query observations by folder prefix (already supports LIKE wildcards) |
-| `updateCursorContextForProject()` | `src/services/integrations/CursorHooksInstaller.ts:98` | Write context files after observation save |
-| `writeContextFile()` | `src/utils/cursor-utils.ts:97` | Atomic file write with temp file + rename |
-| `extractFirstFile()` | `src/shared/timeline-formatting.ts` | Extract file paths from JSON arrays |
-| `groupByDate()` | `src/shared/timeline-formatting.ts` | Group items chronologically |
-| `formatTime()`, `formatDate()` | `src/shared/timeline-formatting.ts` | Time formatting |
-
-### Existing Integration Points
-
-| Location | What Happens | Extension Point |
-|----------|--------------|-----------------|
-| `ResponseProcessor.ts:266` | Calls `updateCursorContextForProject()` after summary save | Add folder CLAUDE.md update here |
-| `CursorHooksInstaller.ts:98` | `updateCursorContextForProject()` fetches context and writes file | Add sibling function for folder updates |
-
-### Anti-Patterns to AVOID
-- Creating `FolderIndexOrchestrator.ts` — NO
-- Creating `FolderTimelineCompiler.ts` — NO
-- Creating `FolderDiscovery.ts` — NO
-- Creating `ClaudeMdGenerator.ts` — NO
-- Creating `FolderIndexRoutes.ts` — NO
-- Adding new HTTP endpoints — NO
-- Adding new settings in `SettingsDefaultsManager.ts` — NO (use sensible defaults inline)
-
----
-
-## Phase 1: Extend CursorHooksInstaller
-
-### What to Implement
-
-Add ONE new function to `src/services/integrations/CursorHooksInstaller.ts`:
-
-```typescript
-/**
- * Update CLAUDE.md files for folders touched by an observation.
- * Called inline after observation save, similar to updateCursorContextForProject.
- */
-export async function updateFolderClaudeMd(
-  workspacePath: string,
-  filesModified: string[],
-  filesRead: string[],
-  project: string,
-  port: number
-): Promise<void>
-```
-
-### Implementation Pattern (Copy From)
-
-Follow the EXACT pattern of `updateCursorContextForProject()` at line 98:
-1. Extract unique folder paths from filesModified and filesRead
-2. For each folder, fetch timeline via existing `/api/search/file?files=<folderPath>` endpoint
-3. Format as simple timeline (reuse existing formatters)
-4. Write to `<folder>/CLAUDE.md` preserving content outside `<claude-mem-context>` tags
-
-### Tag Preservation Logic
-
-```typescript
-function replaceTaggedContent(existingContent: string, newContent: string): string {
-  const startTag = '<claude-mem-context>';
-  const endTag = '</claude-mem-context>';
-
-  // If no existing content, wrap new content in tags
-  if (!existingContent) {
-    return `${startTag}\n${newContent}\n${endTag}`;
-  }
-
-  // If existing has tags, replace only tagged section
-  const startIdx = existingContent.indexOf(startTag);
-  const endIdx = existingContent.indexOf(endTag);
-
-  if (startIdx !== -1 && endIdx !== -1) {
-    return existingContent.substring(0, startIdx) +
-           `${startTag}\n${newContent}\n${endTag}` +
-           existingContent.substring(endIdx + endTag.length);
-  }
-
-  // If no tags exist, append tagged content at end
-  return existingContent + `\n\n${startTag}\n${newContent}\n${endTag}`;
-}
-```
-
-### Verification Checklist
-- [ ] Function added to CursorHooksInstaller.ts
-- [ ] Uses existing `findByFile` endpoint (no new database queries)
-- [ ] Preserves content outside `<claude-mem-context>` tags
-- [ ] Atomic writes (temp file + rename)
-- [ ] Build passes: `npm run build`
-
----
-
-## Phase 2: Hook Into ResponseProcessor
-
-### What to Implement
-
-Add call to `updateFolderClaudeMd()` in `src/services/worker/agents/ResponseProcessor.ts`, right after the existing `updateCursorContextForProject()` call at line 266.
-
-### Code Location
-
-In `syncAndBroadcastSummary()` function, after line 269:
-
-```typescript
-// EXISTING: Update Cursor context file for registered projects (fire-and-forget)
-updateCursorContextForProject(session.project, getWorkerPort()).catch(error => {
-  logger.warn('CURSOR', 'Context update failed (non-critical)', { project: session.project }, error as Error);
-});
-
-// NEW: Update folder CLAUDE.md files for touched folders (fire-and-forget)
-// Extract file paths from the saved observations
-updateFolderClaudeMd(
-  workspacePath,  // From registry lookup
-  filesModified,  // From observations
-  filesRead,      // From observations
-  session.project,
-  getWorkerPort()
-).catch(error => {
-  logger.warn('FOLDER_INDEX', 'CLAUDE.md update failed (non-critical)', { project: session.project }, error as Error);
-});
-```
-
-### Data Flow
-1. `processAgentResponse()` saves observations → gets back `observationIds`
-2. Fetch observation records to get `files_read` and `files_modified`
-3. Pass to `updateFolderClaudeMd()`
-
-### Verification Checklist
-- [ ] Call added to ResponseProcessor.ts
-- [ ] Fire-and-forget pattern (non-blocking, errors logged)
-- [ ] Uses existing observation data (no new queries)
-- [ ] Build passes: `npm run build`
-
----
-
-## Phase 3: Timeline Formatting
-
-### What to Implement
-
-Create a minimal timeline formatter for CLAUDE.md output. This can be:
-1. A simple function in CursorHooksInstaller.ts, OR
-2. Reuse existing `ResultFormatter.formatSearchResults()` from `src/services/worker/search/ResultFormatter.ts`
-
-### Output Format
-
-```markdown
-# Recent Activity
-
-<!-- This section is auto-generated by claude-mem. Edit content outside the tags. -->
-<claude-mem-context>
-
-### 2026-01-04
-
-| Time | Type | Title |
-|------|------|-------|
-| 4:30pm | feature | Added folder index support |
-| 3:15pm | bugfix | Fixed file path handling |
-
-### 2026-01-03
-
-| Time | Type | Title |
-|------|------|-------|
-| 11:00am | refactor | Cleaned up cursor utils |
-
-</claude-mem-context>
-```
-
-### Key Points
-- Compact format (time, type emoji, title only)
-- Grouped by date
-- Limited to last N days or observations (sensible default: 10)
-- NO token counts
-- NO file columns (redundant - we're IN the folder)
-
-### Verification Checklist
-- [ ] Formatter produces clean markdown
-- [ ] Output is concise (not verbose)
-- [ ] Grouped by date
-- [ ] Build passes: `npm run build`
-
----
-
-## Phase 4: Verification
-
-### Functional Tests
-
-1. **Manual Test**:
-   - Start worker: `npm run dev`
-   - Create a test observation touching `src/services/sqlite/`
-   - Verify `src/services/sqlite/CLAUDE.md` is created/updated
-   - Verify `<claude-mem-context>` tags are present
-   - Verify manual content outside tags is preserved
-
-2. **Build Check**:
-   ```bash
-   npm run build
-   ```
-
-3. **Grep for Anti-Patterns**:
-   ```bash
-   # Should find NOTHING
-   grep -r "FolderIndexOrchestrator" src/
-   grep -r "FolderTimelineCompiler" src/
-   grep -r "FolderDiscovery" src/
-   grep -r "ClaudeMdGenerator" src/
-   grep -r "FolderIndexRoutes" src/
-   ```
-
-4. **Grep for Correct Implementation**:
-   ```bash
-   # Should find the new function
-   grep -r "updateFolderClaudeMd" src/
-   ```
-
-### Tag Preservation Test
-
-1. Create `src/test-folder/CLAUDE.md` with manual content:
-   ```markdown
-   # My Notes
-   This is manual content I wrote.
-   ```
-
-2. Trigger observation save touching files in `src/test-folder/`
-
-3. Verify result:
-   ```markdown
-   # My Notes
-   This is manual content I wrote.
-
-   <claude-mem-context>
-   ### 2026-01-04
-   | Time | Type | Title |
-   ...
-   </claude-mem-context>
-   ```
-
----
-
-## Summary
-
-This is a **~100 line change** spread across 2 files:
-1. `CursorHooksInstaller.ts` — Add `updateFolderClaudeMd()` function (~60 lines)
-2. `ResponseProcessor.ts` — Add call to the new function (~10 lines)
-
-NO new files. NO new services. NO new routes. Just extending existing patterns.

.claude/plans/folder-claude-md-refactor.md

@@ -1,378 +0,0 @@
-# Folder CLAUDE.md Refactor - Extract to Shared Utils
-
-## CORE DIRECTIVE
-
-**DECOUPLE FOLDER CLAUDE.MD WRITING FROM CURSOR INTEGRATION**
-
-The current implementation incorrectly couples folder-level CLAUDE.md generation to Cursor-specific registry lookups. The file paths from observations are already absolute - no workspace registry lookup is needed.
-
----
-
-## Phase 0: Documentation Discovery (COMPLETED)
-
-### Current Implementation Location
-
-| Function | Location | Lines | Purpose |
-|----------|----------|-------|---------|
-| `updateFolderClaudeMd` | CursorHooksInstaller.ts | 128-199 | Orchestrates folder CLAUDE.md updates |
-| `formatTimelineForClaudeMd` | CursorHooksInstaller.ts | 221-295 | Parses API response to markdown |
-| `replaceTaggedContent` | CursorHooksInstaller.ts | 300-321 | Preserves user content outside tags |
-| `writeFolderClaudeMd` | CursorHooksInstaller.ts | 326-353 | Atomic file write |
-
-### Integration Point
-
-**File:** `src/services/worker/agents/ResponseProcessor.ts:274-298`
-
-Current (problematic) code:
-```typescript
-const registry = readCursorRegistry();
-const registryEntry = registry[session.project];
-
-if (registryEntry && (filesModified.length > 0 || filesRead.length > 0)) {
-  updateFolderClaudeMd(
-    registryEntry.workspacePath,  // <-- PROBLEM: Needs Cursor registry
-    filesModified,
-    filesRead,
-    session.project,
-    getWorkerPort()
-  ).catch(error => { ... });
-}
-```
-
-### The Problem
-
-1. `filesModified` and `filesRead` already contain **absolute paths**
-2. We don't need `workspacePath` - just extract folder from file path directly
-3. Cursor registry is only populated when Cursor hooks are installed
-4. This makes folder CLAUDE.md a Cursor-only feature (unintended)
-
-### Project Utils Pattern
-
-**From `src/utils/cursor-utils.ts:97-122`:**
-- Pure functions with paths as parameters
-- Atomic write pattern: temp file + rename
-- `mkdirSync(dir, { recursive: true })` for directory creation
-
-### Related Utils
-
-**`src/utils/tag-stripping.ts`** - Handles *stripping* tags (input filtering)
-- `stripMemoryTagsFromJson()` - removes `<claude-mem-context>` content
-- `stripMemoryTagsFromPrompt()` - removes `<private>` content
-
-Our `replaceTaggedContent` handles *preserving/replacing* (output writing) - complementary, not duplicative.
-
----
-
-## Phase 1: Create Shared Utils File
-
-### What to Implement
-
-Create `src/utils/claude-md-utils.ts` with extracted and simplified functions.
-
-### File Structure
-
-```typescript
-/**
- * CLAUDE.md File Utilities
- *
- * Shared utilities for writing folder-level CLAUDE.md files with
- * auto-generated context sections. Preserves user content outside
- * <claude-mem-context> tags.
- */
-
-import { existsSync, readFileSync, writeFileSync, renameSync, mkdirSync } from 'fs';
-import path from 'path';
-import { logger } from './logger.js';
-
-/**
- * Replace tagged content in existing file, preserving content outside tags.
- *
- * Handles three cases:
- * 1. No existing content → wraps new content in tags
- * 2. Has existing tags → replaces only tagged section
- * 3. No tags in existing content → appends tagged content at end
- */
-export function replaceTaggedContent(existingContent: string, newContent: string): string {
-  // Copy from CursorHooksInstaller.ts:300-321
-}
-
-/**
- * Write CLAUDE.md file to folder with atomic writes.
- * Creates directory structure if needed.
- *
- * @param folderPath - Absolute path to the folder
- * @param newContent - Content to write inside tags
- */
-export function writeClaudeMdToFolder(folderPath: string, newContent: string): void {
-  // Simplified from writeFolderClaudeMd - no workspacePath needed
-  // Copy atomic write pattern from CursorHooksInstaller.ts:326-353
-}
-
-/**
- * Format timeline text from API response to compact CLAUDE.md format.
- *
- * @param timelineText - Raw API response text
- * @returns Formatted markdown with date headers and compact table
- */
-export function formatTimelineForClaudeMd(timelineText: string): string {
-  // Copy from CursorHooksInstaller.ts:221-295
-}
-```
-
-### Key Simplification
-
-**OLD `writeFolderClaudeMd` signature:**
-```typescript
-async function writeFolderClaudeMd(
-  workspacePath: string,  // <-- REMOVE
-  folderPath: string,
-  newContent: string
-): Promise<void>
-```
-
-**NEW `writeClaudeMdToFolder` signature:**
-```typescript
-export function writeClaudeMdToFolder(
-  folderPath: string,     // Must be absolute path
-  newContent: string
-): void                   // Sync is fine, atomic anyway
-```
-
-### Verification Checklist
-- [ ] File created at `src/utils/claude-md-utils.ts`
-- [ ] `replaceTaggedContent` exported and handles all 3 cases
-- [ ] `writeClaudeMdToFolder` exported with atomic writes
-- [ ] `formatTimelineForClaudeMd` exported
-- [ ] Build passes: `npm run build`
-
----
-
-## Phase 2: Create Folder Index Service Function
-
-### What to Implement
-
-Create a new orchestrating function that replaces `updateFolderClaudeMd`. This should NOT be in CursorHooksInstaller - it's a general feature.
-
-**Option A:** Add to `src/utils/claude-md-utils.ts` (keeps it simple)
-**Option B:** Create `src/services/folder-index-service.ts` (follows service pattern)
-
-Recommend **Option A** for simplicity - it's just one function.
-
-### New Function
-
-```typescript
-/**
- * Update CLAUDE.md files for folders containing the given files.
- * Fetches timeline from worker API and writes formatted content.
- *
- * @param filePaths - Array of absolute file paths (modified or read)
- * @param project - Project identifier for API query
- * @param port - Worker API port
- */
-export async function updateFolderClaudeMdFiles(
-  filePaths: string[],
-  project: string,
-  port: number
-): Promise<void> {
-  // Extract unique folder paths from file paths
-  const folderPaths = new Set<string>();
-  for (const filePath of filePaths) {
-    if (!filePath || filePath === '') continue;
-    const folderPath = path.dirname(filePath);
-    if (folderPath && folderPath !== '.' && folderPath !== '/') {
-      folderPaths.add(folderPath);
-    }
-  }
-
-  if (folderPaths.size === 0) return;
-
-  logger.debug('FOLDER_INDEX', 'Updating CLAUDE.md files', {
-    project,
-    folderCount: folderPaths.size
-  });
-
-  // Process each folder
-  for (const folderPath of folderPaths) {
-    try {
-      // Fetch timeline via existing API
-      const response = await fetch(
-        `http://127.0.0.1:${port}/api/search/by-file?filePath=${encodeURIComponent(folderPath)}&limit=10&project=${encodeURIComponent(project)}`
-      );
-
-      if (!response.ok) {
-        logger.warn('FOLDER_INDEX', 'Failed to fetch timeline', { folderPath, status: response.status });
-        continue;
-      }
-
-      const result = await response.json();
-      if (!result.content?.[0]?.text) {
-        logger.debug('FOLDER_INDEX', 'No content for folder', { folderPath });
-        continue;
-      }
-
-      const formatted = formatTimelineForClaudeMd(result.content[0].text);
-      writeClaudeMdToFolder(folderPath, formatted);
-
-      logger.debug('FOLDER_INDEX', 'Updated CLAUDE.md', { folderPath });
-    } catch (error) {
-      logger.warn('FOLDER_INDEX', 'Failed to update CLAUDE.md', { folderPath }, error as Error);
-    }
-  }
-}
-```
-
-### Verification Checklist
-- [ ] `updateFolderClaudeMdFiles` function added
-- [ ] Takes only `filePaths`, `project`, `port` (no workspacePath)
-- [ ] Extracts folder paths from absolute file paths
-- [ ] Uses `writeClaudeMdToFolder` for atomic writes
-- [ ] Build passes: `npm run build`
-
----
-
-## Phase 3: Update ResponseProcessor Integration
-
-### What to Implement
-
-Simplify the call site in `src/services/worker/agents/ResponseProcessor.ts`.
-
-### Current Code (lines 274-298)
-```typescript
-// Update folder CLAUDE.md files for touched folders (fire-and-forget)
-const filesModified: string[] = [];
-const filesRead: string[] = [];
-
-for (const obs of observations) {
-  filesModified.push(...(obs.files_modified || []));
-  filesRead.push(...(obs.files_read || []));
-}
-
-// Get workspace path from project registry
-const registry = readCursorRegistry();
-const registryEntry = registry[session.project];
-
-if (registryEntry && (filesModified.length > 0 || filesRead.length > 0)) {
-  updateFolderClaudeMd(
-    registryEntry.workspacePath,
-    filesModified,
-    filesRead,
-    session.project,
-    getWorkerPort()
-  ).catch(error => {
-    logger.warn('FOLDER_INDEX', 'CLAUDE.md update failed (non-critical)', { project: session.project }, error as Error);
-  });
-}
-```
-
-### New Code
-```typescript
-// Update folder CLAUDE.md files for touched folders (fire-and-forget)
-const allFilePaths: string[] = [];
-for (const obs of observations) {
-  allFilePaths.push(...(obs.files_modified || []));
-  allFilePaths.push(...(obs.files_read || []));
-}
-
-if (allFilePaths.length > 0) {
-  updateFolderClaudeMdFiles(
-    allFilePaths,
-    session.project,
-    getWorkerPort()
-  ).catch(error => {
-    logger.warn('FOLDER_INDEX', 'CLAUDE.md update failed (non-critical)', { project: session.project }, error as Error);
-  });
-}
-```
-
-### Import Changes
-
-**Remove:**
-```typescript
-import { updateFolderClaudeMd, readCursorRegistry } from '../../integrations/CursorHooksInstaller.js';
-```
-
-**Add:**
-```typescript
-import { updateFolderClaudeMdFiles } from '../../../utils/claude-md-utils.js';
-```
-
-**Keep (if still needed for Cursor context):**
-```typescript
-import { updateCursorContextForProject } from '../../worker-service.js';
-```
-
-### Verification Checklist
-- [ ] Import updated to use `claude-md-utils.ts`
-- [ ] `readCursorRegistry` import removed (if no longer needed)
-- [ ] Call site simplified - no registry lookup
-- [ ] Fire-and-forget pattern preserved
-- [ ] Build passes: `npm run build`
-
----
-
-## Phase 4: Clean Up CursorHooksInstaller
-
-### What to Implement
-
-Remove the extracted functions from `src/services/integrations/CursorHooksInstaller.ts`.
-
-### Functions to Remove
-- `updateFolderClaudeMd` (lines 128-199)
-- `formatTimelineForClaudeMd` (lines 221-295)
-- `replaceTaggedContent` (lines 300-321)
-- `writeFolderClaudeMd` (lines 326-353)
-
-### Verification Checklist
-- [ ] All 4 functions removed from CursorHooksInstaller.ts
-- [ ] No dangling references to removed functions
-- [ ] CursorHooksInstaller still exports what it needs for Cursor integration
-- [ ] Build passes: `npm run build`
-- [ ] Grep shows no references to old function locations
-
----
-
-## Phase 5: Verification
-
-### Build Check
-```bash
-npm run build
-```
-
-### Anti-Pattern Grep (should find NOTHING in CursorHooksInstaller)
-```bash
-grep -n "updateFolderClaudeMd\|formatTimelineForClaudeMd\|replaceTaggedContent\|writeFolderClaudeMd" src/services/integrations/CursorHooksInstaller.ts
-```
-
-### Correct Location Grep (should find in claude-md-utils)
-```bash
-grep -rn "updateFolderClaudeMdFiles\|writeClaudeMdToFolder\|formatTimelineForClaudeMd" src/utils/
-```
-
-### Integration Check
-```bash
-grep -n "updateFolderClaudeMdFiles" src/services/worker/agents/ResponseProcessor.ts
-```
-
-### No Cursor Registry Dependency
-```bash
-grep -n "readCursorRegistry" src/services/worker/agents/ResponseProcessor.ts
-# Should return nothing (or only for Cursor context, not folder index)
-```
-
----
-
-## Summary
-
-**~150 lines moved** from CursorHooksInstaller.ts to claude-md-utils.ts with simplification:
-
-| Before | After |
-|--------|-------|
-| 4 functions in CursorHooksInstaller | 4 functions in claude-md-utils |
-| Requires Cursor registry lookup | Works with absolute paths directly |
-| `updateFolderClaudeMd(workspacePath, ...)` | `updateFolderClaudeMdFiles(filePaths, ...)` |
-| Coupled to Cursor integration | Independent utility |
-
-**Files Changed:**
-1. `src/utils/claude-md-utils.ts` - NEW (create)
-2. `src/services/worker/agents/ResponseProcessor.ts` - UPDATE (simplify call site)
-3. `src/services/integrations/CursorHooksInstaller.ts` - UPDATE (remove extracted functions)

.claude/plans/folder-claude-md-timeline-format.md

@@ -1,186 +0,0 @@
-# Plan: Change Folder CLAUDE.md to Timeline Format
-
-## Goal
-
-Replace the simple table format in folder-level CLAUDE.md files with the timeline format used by search results.
-
-## Current vs Target Format
-
-### Current Format (Simple)
-```markdown
-# Recent Activity
-
-### Recent
-
-| Time | Type | Title |
-|------|------|-------|
-| 6:33pm | feature | Multiple CLAUDE.md files generated |
-| 6:32pm | feature | CLAUDE.md file successfully generated |
-```
-
-### Target Format (Timeline)
-```markdown
-# Recent Activity
-
-### Jan 4, 2026
-
-**src/services/worker/agents/ResponseProcessor.ts**
-| ID | Time | T | Title | Read |
-|----|------|---|-------|------|
-| #37110 | 6:35 PM | 🔴 | Folder CLAUDE.md updates moved from summary | ~85 |
-| #37109 | " | ✅ | ResponseProcessor.ts modified | ~92 |
-
-**General**
-| ID | Time | T | Title | Read |
-|----|------|---|-------|------|
-| #37108 | 6:33 PM | 🟣 | Multiple CLAUDE.md files generated | ~78 |
-```
-
-## Key Changes
-
-1. **Group by date** - Use `### Jan 4, 2026` instead of `### Recent`
-2. **Group by file within each date** - Add `**filename**` headers
-3. **Expand columns** - Add ID and Read columns: `| ID | Time | T | Title | Read |`
-4. **Use type emojis** - Use `🔴` `🟣` `✅` etc. instead of text
-5. **Show ditto marks** - Use `"` for repeated times
-
----
-
-## Phase 1: Refactor formatTimelineForClaudeMd
-
-**File:** `src/utils/claude-md-utils.ts`
-
-**Tasks:**
-
-1. Add imports from shared utilities:
-   ```typescript
-   import { formatDate, formatTime, extractFirstFile, estimateTokens, groupByDate } from '../shared/timeline-formatting.js';
-   import { ModeManager } from '../services/domain/ModeManager.js';
-   ```
-
-2. Replace `formatTimelineForClaudeMd()` (lines 78-151) with new implementation that:
-   - Parses API response to extract full observation data (id, time, type emoji, title, files)
-   - Groups observations by date using `groupByDate()`
-   - Within each date, groups by file using a Map
-   - Renders file sections with `**filename**` headers
-   - Uses search table format: `| ID | Time | T | Title | Read |`
-   - Uses ditto marks for repeated times
-
-**Pattern to Copy From:** `src/services/worker/search/ResultFormatter.ts` lines 56-108
-
-**Key APIs:**
-- `groupByDate(items, getDate)` - from `src/shared/timeline-formatting.ts:104-127`
-- `formatTime(epoch)` - from `src/shared/timeline-formatting.ts:46-53`
-- `formatDate(epoch)` - from `src/shared/timeline-formatting.ts:59-66`
-- `extractFirstFile(filesModified, cwd)` - from `src/shared/timeline-formatting.ts:81-84`
-- `estimateTokens(text)` - from `src/shared/timeline-formatting.ts:89-92`
-- `ModeManager.getInstance().getTypeIcon(type)` - from `src/services/domain/ModeManager.ts`
-
-**Verification:**
-1. Run `npm run build` - no errors
-2. Restart worker: `npm run worker:restart`
-3. Make a test edit to trigger observation
-4. Check generated CLAUDE.md files for new format
-
----
-
-## Phase 2: Parse Full Observation Data from API
-
-**Context:** The current regex parsing extracts only time, type emoji, and title. Need to also extract:
-- Observation ID (for `#123` column)
-- File path (from files_modified in API response, for grouping)
-- Token estimate (for `Read` column)
-
-**Challenge:** The current API returns formatted text, not structured data. We need to:
-1. Parse the existing text format more thoroughly, OR
-2. Use a different API endpoint that returns JSON
-
-**Decision Point:** Check what data the `/api/search/by-file` endpoint returns. If it returns structured JSON with observations, use that. Otherwise, enhance parsing.
-
-**Investigation Required:**
-- Read `src/services/worker/http/routes/SearchRoutes.ts` to see by-file response format
-- Determine if we can access raw observation data or just formatted text
-
-**Verification:**
-- Confirm API response structure
-- Update parsing to extract all needed fields
-
----
-
-## Phase 3: Integrate File-Based Grouping
-
-**File:** `src/utils/claude-md-utils.ts`
-
-**Tasks:**
-
-1. Create helper to group by file:
-   ```typescript
-   function groupByFile(observations: ParsedObservation[]): Map<string, ParsedObservation[]> {
-     const byFile = new Map<string, ParsedObservation[]>();
-     for (const obs of observations) {
-       const file = obs.file || 'General';
-       if (!byFile.has(file)) byFile.set(file, []);
-       byFile.get(file)!.push(obs);
-     }
-     return byFile;
-   }
-   ```
-
-2. Render with file sections:
-   ```typescript
-   for (const [file, fileObs] of resultsByFile) {
-     lines.push(`**${file}**`);
-     lines.push(`| ID | Time | T | Title | Read |`);
-     lines.push(`|----|------|---|-------|------|`);
-     // render rows with ditto marks
-   }
-   ```
-
-**Pattern to Copy From:** `ResultFormatter.formatSearchResults()` lines 60-108
-
-**Verification:**
-- Generated CLAUDE.md shows file grouping
-- Files are displayed as relative paths when possible
-
----
-
-## Phase 4: Final Verification
-
-**Checklist:**
-
-1. **Build passes:** `npm run build`
-2. **Worker restarts cleanly:** `npm run worker:restart`
-3. **Format matches target:**
-   - Date headers: `### Jan 4, 2026`
-   - File sections: `**filename**`
-   - Table columns: `| ID | Time | T | Title | Read |`
-   - Type emojis: `🔴` `🟣` `✅` not text
-   - Ditto marks: `"` for repeated times
-4. **Anti-pattern checks:**
-   - No hardcoded type maps (use ModeManager)
-   - No invented APIs
-   - Reuses existing formatters from shared utils
-5. **Graceful degradation:** Empty results still show `*No recent activity*`
-
----
-
-## Files to Modify
-
-| File | Change |
-|------|--------|
-| `src/utils/claude-md-utils.ts` | Replace `formatTimelineForClaudeMd()` with timeline format |
-
-## Files to Read (Patterns to Copy)
-
-| File | Pattern |
-|------|---------|
-| `src/services/worker/search/ResultFormatter.ts:56-108` | Date/file grouping logic |
-| `src/shared/timeline-formatting.ts` | All formatting utilities |
-| `src/services/domain/ModeManager.ts` | Type icon lookup |
-
-## Anti-Patterns to Avoid
-
-- ❌ Creating new hardcoded type→emoji maps (use ModeManager)
-- ❌ Parsing dates manually (use shared formatters)
-- ❌ Skipping the existing groupByDate utility
-- ❌ Not handling ditto marks for repeated times

.claude/plans/intentional-patterns-execution.md

@@ -1,356 +0,0 @@
-# Execution Plan: Intentional Patterns Validation Actions
-
-**Created:** 2026-01-13
-**Source:** `docs/reports/intentional-patterns-validation.md`
-**Target:** `src/services/worker-service.ts` and related files
-
----
-
-## Phase 0: Documentation Discovery (COMPLETED)
-
-### Evidence Gathered
-
-**Files Analyzed:**
-- `docs/reports/intentional-patterns-validation.md` - Pattern verdicts and recommendations
-- `docs/reports/nonsense-logic.md` - Original 23 issues identified
-- `.claude/plans/cleanup-worker-service-nonsense-logic.md` - Existing cleanup plan
-- `src/services/worker-service.ts` (813 lines) - Current state
-
-**Current State:**
-- File has been reduced from 1445 lines to 813 lines in prior refactoring
-- `runInteractiveSetup` still exists at line 439 (~200 lines of dead code)
-- Re-export at line 78: `export { updateCursorContextForProject };`
-- MCP version hardcoded "1.0.0" at line 159
-- Fallback agents set at lines 144-146 without verification
-- Unused imports: `fs`, `spawn`, `homedir`, `readline` at lines 13-17
-
-**Allowed APIs (from validation report):**
-- Exit code 0 pattern: **KEEP** (documented Windows Terminal workaround)
-- `as Error` casts: **KEEP** (documented project policy)
-- Dual init tracking: **KEEP** (serves async + sync callers)
-- Signal handler ref pattern: **KEEP** (standard JS mutable state sharing)
-- Empty MCP capabilities: **KEEP** (correct per MCP spec)
-
-**Actions Required:**
-| Pattern | Action | Priority |
-|---------|--------|----------|
-| Re-export for circular import | Remove (no actual circular dep) | LOW |
-| Fallback agent without check | Add availability verification | HIGH |
-| MCP version hardcoded | Update to use package.json | LOW |
-| Dead code `runInteractiveSetup` | Delete (~200 lines) | HIGH |
-| Unused imports | Delete | LOW |
-
----
-
-## Phase 1: Delete Dead Code (HIGH PRIORITY)
-
-### 1.1 Delete `runInteractiveSetup` Function
-
-**What:** Delete lines 435-639 (approximately 200 lines)
-**File:** `src/services/worker-service.ts`
-
-**Location confirmed:** Line 439 starts `async function runInteractiveSetup(): Promise<number>`
-
-**Steps:**
-1. Read worker-service.ts lines 435-650 to find exact boundaries
-2. Delete the section comment and entire function
-3. Run build to verify no compile errors
-
-**Verification:**
-```bash
-grep -n "runInteractiveSetup" src/services/worker-service.ts
-# Expected: No output (function deleted)
-npm run build
-# Expected: No errors
-```
-
-### 1.2 Remove Unused Imports
-
-**What:** Delete imports only used by dead code
-**Lines to delete:** 13-17 (check each)
-
-**Current imports to remove:**
-```typescript
-import * as fs from 'fs';              // Line 13 - UNUSED (namespace never accessed)
-import { spawn } from 'child_process'; // Line 14 - UNUSED (MCP uses StdioClientTransport)
-import { homedir } from 'os';          // Line 15 - Only in dead code
-import * as readline from 'readline';  // Line 17 - Only in dead code
-```
-
-**Keep:**
-```typescript
-import { existsSync, writeFileSync, readFileSync, mkdirSync } from 'fs';  // Line 16 - CHECK
-```
-
-**Steps:**
-1. After deleting `runInteractiveSetup`, grep each import
-2. Delete any with zero usages
-3. Run build to verify
-
-**Verification:**
-```bash
-grep -n "^import \* as fs" src/services/worker-service.ts
-grep -n "import { spawn }" src/services/worker-service.ts
-# Expected: No output
-npm run build
-```
-
-### 1.3 Remove Unused CursorHooksInstaller Imports
-
-**After deleting dead code, check:**
-```typescript
-import {
-  updateCursorContextForProject,  // KEEP (re-exported)
-  handleCursorCommand,            // KEEP (used in main)
-  detectClaudeCode,               // DELETE (only in dead code)
-  findCursorHooksDir,             // DELETE (only in dead code)
-  installCursorHooks,             // DELETE (only in dead code)
-  configureCursorMcp              // DELETE (only in dead code)
-} from './integrations/CursorHooksInstaller.js';
-```
-
-**Verification:**
-```bash
-grep "detectClaudeCode\|findCursorHooksDir\|installCursorHooks\|configureCursorMcp" src/services/worker-service.ts
-# Expected: Only import line (which gets trimmed)
-```
-
----
-
-## Phase 2: Fix Fallback Agent Oversight (HIGH PRIORITY)
-
-### 2.1 Add SDKAgent Availability Check
-
-**Problem:** Lines 144-146 set Claude SDK as fallback without verifying it's configured
-```typescript
-this.geminiAgent.setFallbackAgent(this.sdkAgent);
-this.openRouterAgent.setFallbackAgent(this.sdkAgent);
-```
-
-**Risk:** User chooses Gemini because they lack Claude credentials → transient Gemini error → fallback to Claude SDK → cascading failure
-
-**Solution Options:**
-
-**Option A: Add isConfigured() method to SDKAgent**
-1. Add method to SDKAgent that checks for valid Claude SDK credentials
-2. Only set fallback if `sdkAgent.isConfigured()` returns true
-3. Log warning when fallback unavailable
-
-**Pattern to follow (from SDKAgent.ts constructor):**
-```typescript
-// Check if Claude SDK can be initialized
-public isConfigured(): boolean {
-  // Claude SDK uses subprocess, check if claude command exists
-  try {
-    // Check for ANTHROPIC_API_KEY or claude CLI availability
-    return !!process.env.ANTHROPIC_API_KEY || this.checkClaudeCliAvailable();
-  } catch {
-    return false;
-  }
-}
-```
-
-**Option B: Document limitation (minimal fix)**
-Add comment explaining the risk:
-```typescript
-// NOTE: Fallback to Claude SDK may fail if user lacks Claude credentials
-// Consider adding availability check in future (Issue #XXX)
-this.geminiAgent.setFallbackAgent(this.sdkAgent);
-```
-
-**Recommended: Option A**
-
-**Steps:**
-1. Read SDKAgent.ts to understand initialization pattern
-2. Add `isConfigured()` method that checks Claude CLI/credentials
-3. Update worker-service.ts to conditionally set fallback
-4. Add warning log when fallback unavailable
-5. Run tests
-
-**Verification:**
-```bash
-grep -n "isConfigured" src/services/worker/SDKAgent.ts
-# Expected: Method definition
-grep -n "setFallbackAgent" src/services/worker-service.ts
-# Expected: Conditional calls with isConfigured check
-npm test
-```
-
----
-
-## Phase 3: Remove Unnecessary Re-Export (LOW PRIORITY)
-
-### 3.1 Fix Misleading Re-Export
-
-**Current (worker-service.ts:77-78):**
-```typescript
-// Re-export updateCursorContextForProject for SDK agents
-export { updateCursorContextForProject };
-```
-
-**Issue:** Comment implies avoiding circular import, but investigation found NO circular dependency exists.
-
-**Import chain:**
-```
-CursorHooksInstaller.ts (defines) → worker-service.ts (imports, re-exports) → ResponseProcessor.ts (imports)
-```
-
-**ResponseProcessor.ts could import directly from CursorHooksInstaller.ts**
-
-**Options:**
-1. **Remove re-export entirely** - Update ResponseProcessor.ts to import from CursorHooksInstaller directly
-2. **Fix comment** - Update to reflect actual reason (API surface simplification)
-
-**Recommended: Option 1 (cleaner)**
-
-**Steps:**
-1. Update `src/services/worker/agents/ResponseProcessor.ts`:
-   - Change: `import { updateCursorContextForProject } from '../../worker-service.js';`
-   - To: `import { updateCursorContextForProject } from '../../integrations/CursorHooksInstaller.js';`
-2. Delete re-export from worker-service.ts (lines 77-78)
-3. Run build to verify
-
-**Verification:**
-```bash
-grep -n "export { updateCursorContextForProject" src/services/worker-service.ts
-# Expected: No output
-grep -n "updateCursorContextForProject" src/services/worker/agents/ResponseProcessor.ts
-# Expected: Import from CursorHooksInstaller
-npm run build
-```
-
----
-
-## Phase 4: Update MCP Version (LOW PRIORITY)
-
-### 4.1 Use Package Version for MCP Client
-
-**Current (worker-service.ts:157-160):**
-```typescript
-this.mcpClient = new Client({
-  name: 'worker-search-proxy',
-  version: '1.0.0'  // Hardcoded, should match package.json (9.0.4)
-}, { capabilities: {} });
-```
-
-**Also affects (from report):**
-- `src/services/sync/ChromaSync.ts:126-131`
-- MCP server (separate file)
-
-**Pattern to follow:**
-```typescript
-import { version } from '../../package.json' assert { type: 'json' };
-
-this.mcpClient = new Client({
-  name: 'worker-search-proxy',
-  version: version
-}, { capabilities: {} });
-```
-
-**Alternative (if JSON import not supported):**
-```typescript
-import { readFileSync } from 'fs';
-const pkg = JSON.parse(readFileSync(new URL('../../package.json', import.meta.url), 'utf-8'));
-
-this.mcpClient = new Client({
-  name: 'worker-search-proxy',
-  version: pkg.version
-}, { capabilities: {} });
-```
-
-**Steps:**
-1. Check if JSON import assertion works in project
-2. Update worker-service.ts MCP client initialization
-3. Update ChromaSync.ts similarly
-4. Run build to verify
-
-**Verification:**
-```bash
-grep -n "version: '1.0.0'" src/services/worker-service.ts src/services/sync/ChromaSync.ts
-# Expected: No output
-npm run build
-```
-
-### 4.2 Add MCP Capabilities Comment
-
-**Current:**
-```typescript
-}, { capabilities: {} });
-```
-
-**Add clarifying comment:**
-```typescript
-}, {
-  // MCP spec: Clients accept all server capabilities; no declaration needed
-  capabilities: {}
-});
-```
-
----
-
-## Phase 5: Verification
-
-### 5.1 Build Check
-```bash
-npm run build
-```
-**Expected:** No TypeScript errors
-
-### 5.2 Test Suite
-```bash
-npm test
-```
-**Expected:** All tests pass
-
-### 5.3 Grep for Anti-Patterns
-```bash
-# Verify dead code removed
-grep -r "runInteractiveSetup" src/
-# Expected: No matches
-
-# Verify unused imports removed
-grep "import \* as fs from 'fs'" src/services/worker-service.ts
-# Expected: No match
-
-# Verify re-export removed
-grep "export { updateCursorContextForProject" src/services/worker-service.ts
-# Expected: No match
-
-# Verify fallback has check
-grep -A2 "setFallbackAgent" src/services/worker-service.ts
-# Expected: Conditional with isConfigured check
-```
-
-### 5.4 Runtime Check
-```bash
-npm run build-and-sync
-# Manually verify worker starts and basic operations work
-```
-
----
-
-## Summary
-
-| Phase | Description | Lines Changed | Priority |
-|-------|-------------|---------------|----------|
-| Phase 1 | Delete dead code + imports | ~200 deleted | HIGH |
-| Phase 2 | Add fallback verification | ~10 added | HIGH |
-| Phase 3 | Remove re-export | ~5 changed | LOW |
-| Phase 4 | Update MCP version | ~3 changed | LOW |
-| Phase 5 | Verification | N/A | N/A |
-
-**Execution Order:** Phase 1 → Phase 2 → Phase 3 → Phase 4 → Phase 5
-
-**Note:** Each phase should be followed by verification (build + test) before proceeding.
-
----
-
-## Patterns Confirmed KEEP (No Action)
-
-These patterns were validated as intentional:
-
-1. **Exit code 0 always** - Windows Terminal tab accumulation workaround (commit 222a73da)
-2. **`as Error` casts** - Documented project policy with anti-pattern detection
-3. **Dual init tracking** - Promise for async, flag for sync callers
-4. **Signal handler ref pattern** - Standard JS mutable state sharing
-5. **Empty MCP capabilities** - Correct per MCP client spec

.claude/plans/pr-610-review-fixes.md

@@ -1,144 +0,0 @@
-# Plan: Address PR #610 Review Issues
-
-## Overview
-This plan addresses the issues identified in the PR review for PR #610 "fix: Update hooks for Claude Code 2.1.0/1 - SessionStart no longer shows user messages".
-
-## Phase 0: Verification and Discovery
-
-### 0.1 Verify Test Failure
-- **File**: `tests/hook-constants.test.ts`
-- **Issue**: Lines 61-63 test for `HOOK_EXIT_CODES.USER_MESSAGE_ONLY` which was removed
-- **Verification**: Run `bun test tests/hook-constants.test.ts` to confirm failure
-
-### 0.2 Verify No Code References USER_MESSAGE_ONLY
-- **Finding**: Grep found references only in:
-  - `tests/hook-constants.test.ts` (test file - needs fix)
-  - `src/services/CLAUDE.md` (memory context - auto-generated, not code)
-  - `plugin/scripts/CLAUDE.md` (memory context - auto-generated, not code)
-- **Conclusion**: Only the test file needs updating; CLAUDE.md files are memory records
-
-### 0.3 Verify CLAUDE.md Files Are Legitimate
-- **Clarification**: The PR reviewer mentioned "user-specific CLAUDE.md files starting with ~/"
-- **Finding**: All CLAUDE.md files in the commit are within the repository (`docs/`, `src/`, `plugin/`)
-- **Conclusion**: These are legitimate in-repo context files, not user-specific paths
-
----
-
-## Phase 1: Fix Test File (REQUIRED)
-
-### Task 1.1: Remove USER_MESSAGE_ONLY Test
-**File**: `tests/hook-constants.test.ts`
-**Action**: Delete lines 61-63 that test for the removed constant
-
-```typescript
-// DELETE THESE LINES:
-it('should define USER_MESSAGE_ONLY exit code', () => {
-  expect(HOOK_EXIT_CODES.USER_MESSAGE_ONLY).toBe(3);
-});
-```
-
-### Task 1.2: Add Test for BLOCKING_ERROR
-**File**: `tests/hook-constants.test.ts`
-**Action**: Add test for the new `BLOCKING_ERROR` constant (exit code 2) that replaced it
-
-```typescript
-// ADD THIS TEST:
-it('should define BLOCKING_ERROR exit code', () => {
-  expect(HOOK_EXIT_CODES.BLOCKING_ERROR).toBe(2);
-});
-```
-
-### Verification
-- Run `bun test tests/hook-constants.test.ts`
-- Expect: All tests pass
-
----
-
-## Phase 2: Documentation Consistency (NICE TO HAVE)
-
-### Issue
-Three similar notes about Claude Code 2.1.0 have slightly different wording:
-
-1. `docs/public/architecture/hooks.mdx:254`:
-   > "SessionStart hooks no longer display any user-visible messages. Context is still injected via `hookSpecificOutput.additionalContext` but users don't see startup output in the UI."
-
-2. `docs/public/hooks-architecture.mdx:31`:
-   > "SessionStart hooks no longer display any user-visible messages. Context is silently injected via `hookSpecificOutput.additionalContext`."
-
-3. `docs/public/hooks-architecture.mdx:441`:
-   > "SessionStart hooks output is never displayed to users. Context is injected silently via `hookSpecificOutput.additionalContext`."
-
-### Task 2.1: Standardize Note Wording
-**Action**: Use consistent wording across all three locations
-
-**Standard text**:
-```
-As of Claude Code 2.1.0 (ultrathink update), SessionStart hooks no longer display user-visible messages. Context is silently injected via `hookSpecificOutput.additionalContext`.
-```
-
-### Files to Update
-1. `docs/public/architecture/hooks.mdx:253-255` - Update Note block
-2. `docs/public/hooks-architecture.mdx:30-32` - Update Note block
-3. `docs/public/hooks-architecture.mdx:440-442` - Update Note block
-
-### Verification
-- Grep for the standard text in all three files
-- Visual review of documentation
-
----
-
-## Phase 3: Code Quality Improvements (OPTIONAL)
-
-### Issue 3.1: Hardcoded Promotional Message
-**File**: `src/hooks/context-hook.ts:66-68`
-**Current code**:
-```typescript
-const enhancedContext = `${text}
-
-Access 300k tokens of past research & decisions for just 19,008t. Use MCP search tools to access memories by ID.`;
-```
-
-### Options
-1. **Leave as-is**: The token count is a rough estimate and doesn't need to be exact
-2. **Make configurable**: Add to settings (over-engineering for this use case)
-3. **Remove hardcoded numbers**: Use relative language instead
-
-### Recommendation
-Leave as-is for now. The token counts are marketing copy, not critical functionality. Creating a PR just for this adds unnecessary complexity.
-
----
-
-## Phase 4: Final Verification
-
-### 4.1 Run Full Test Suite
-```bash
-bun test
-```
-
-### 4.2 Build Verification
-```bash
-npm run build
-```
-
-### 4.3 Grep Verification
-```bash
-grep -r "USER_MESSAGE_ONLY" src/ --include="*.ts" --include="*.js"
-```
-Expected: No results (CLAUDE.md files excluded as they're memory records)
-
----
-
-## Summary
-
-| Phase | Priority | Effort | Description |
-|-------|----------|--------|-------------|
-| 1 | REQUIRED | 5 min | Fix test file - remove USER_MESSAGE_ONLY test, add BLOCKING_ERROR test |
-| 2 | Nice to have | 10 min | Standardize documentation note wording |
-| 3 | Skip | - | Hardcoded token counts are fine as-is |
-| 4 | REQUIRED | 5 min | Run tests and build to verify |
-
-## Expected Outcome
-- All tests pass
-- Build succeeds
-- No code references to removed USER_MESSAGE_ONLY constant
-- Documentation uses consistent wording (if Phase 2 is done)

.claude/plans/pr-628-polish.md

@@ -1,223 +0,0 @@
-# Plan: PR #628 Polish Items
-
-**PR**: #628 - Windows Terminal Tab Accumulation & Windows 11 Compatibility
-**Status**: APPROVED by 3 reviewers with minor suggestions
-**Branch**: `feature/no-more-hook-files`
-
----
-
-## Phase 0: Documentation Discovery (Completed by Orchestrator)
-
-### Allowed APIs and Patterns
-
-**Exit Code Constants** - `src/shared/hook-constants.ts:18-23`:
-```typescript
-export const HOOK_EXIT_CODES = {
-  SUCCESS: 0,
-  FAILURE: 1,
-  BLOCKING_ERROR: 2,
-} as const;
-```
-
-**Timeout Constants** - `src/shared/hook-constants.ts:1-8`:
-```typescript
-export const HOOK_TIMEOUTS = {
-  DEFAULT: 300000,
-  HEALTH_CHECK: 30000,
-  WORKER_STARTUP_WAIT: 1000,
-  WORKER_STARTUP_RETRIES: 300,
-  PRE_RESTART_SETTLE_DELAY: 2000,
-  WINDOWS_MULTIPLIER: 1.5
-} as const;
-```
-
-**Platform Timeout Function** - `src/services/infrastructure/ProcessManager.ts:70-73`:
-```typescript
-export function getPlatformTimeout(baseMs: number): number {
-  const WINDOWS_MULTIPLIER = 2.0;
-  return process.platform === 'win32' ? Math.round(baseMs * WINDOWS_MULTIPLIER) : baseMs;
-}
-```
-
-**Migration Guide Pattern** - `docs/public/architecture/pm2-to-bun-migration.mdx`:
-- Uses MDX format with frontmatter
-- Starts with `<Note>` for historical context
-- Uses `<AccordionGroup>` for before/after comparisons
-- Includes executive summary, key benefits, migration impact sections
-
-**Exit Code Documentation** - `private/context/claude-code/exit-codes.md`:
-- Defines exit code 0, 2, and other behaviors
-- Per-hook event behavior table
-
-### Files to Modify
-
-| File | Change | Lines |
-|------|--------|-------|
-| `src/services/infrastructure/ProcessManager.ts` | Add POWERSHELL_TIMEOUT constant, reduce from 60000 to 10000 | 93, 123, 175, 241 |
-| `src/shared/hook-constants.ts` | Add POWERSHELL_TIMEOUT constant | After line 8 |
-| `CLAUDE.md` | Document exit code strategy | Architecture section |
-
-### Anti-Patterns to Avoid
-
-- DO NOT invent new exit code values (only 0, 1, 2 exist)
-- DO NOT change Windows multiplier (1.5x in hooks, 2.0x in ProcessManager - they serve different purposes)
-- DO NOT add upper bound PID validation (not in existing pattern, reviewers marked as "nice to have")
-- DO NOT create migration guide for Cursor (shell scripts still exist in cursor-hooks/, not removed)
-
----
-
-## Phase 1: Extract PowerShell Timeout Constant
-
-### What to Implement
-
-Add a `POWERSHELL_TIMEOUT` constant to centralize the magic number `60000` and reduce to `10000` (10 seconds) as recommended by reviewers.
-
-### Documentation References
-
-1. Copy constant pattern from `src/shared/hook-constants.ts:1-8`
-2. Copy usage pattern from `src/services/infrastructure/ProcessManager.ts:93`
-
-### Implementation Steps
-
-1. **Add constant to hook-constants.ts** after line 8:
-   ```typescript
-   POWERSHELL_COMMAND: 10000,     // PowerShell process enumeration (10s - typically completes in <1s)
-   ```
-
-2. **Import and use in ProcessManager.ts**:
-   - Import `HOOK_TIMEOUTS` from `../../shared/hook-constants.js`
-   - Replace `{ timeout: 60000 }` with `{ timeout: HOOK_TIMEOUTS.POWERSHELL_COMMAND }` at lines 93, 123, 175, 241
-
-### Verification Checklist
-
-- [ ] `grep -n "60000" src/services/infrastructure/ProcessManager.ts` returns 0 matches
-- [ ] `grep -n "POWERSHELL_COMMAND" src/services/infrastructure/ProcessManager.ts` returns 4 matches
-- [ ] `npm run build` succeeds
-- [ ] `npm test` passes (22/22 PowerShell tests still pass)
-
-### Anti-Pattern Guards
-
-- DO NOT use `getPlatformTimeout()` for PowerShell commands (they already run only on Windows)
-- DO NOT change timeout values in other files (only ProcessManager.ts uses PowerShell)
-
----
-
-## Phase 2: Document Exit Code Strategy in CLAUDE.md
-
-### What to Implement
-
-Add an "Exit Code Strategy" section to the main CLAUDE.md to explain the graceful exit philosophy adopted in this PR.
-
-### Documentation References
-
-1. Copy exit code definitions from `private/context/claude-code/exit-codes.md`
-2. Follow format of existing CLAUDE.md sections
-
-### Implementation Steps
-
-1. **Add section after "File Locations"** in `/Users/alexnewman/Scripts/claude-mem/CLAUDE.md`:
-
-```markdown
-## Exit Code Strategy
-
-Claude-mem hooks use specific exit codes per Claude Code's hook contract:
-
-- **Exit 0**: Success or graceful shutdown (Windows Terminal closes tabs)
-- **Exit 1**: Non-blocking error (stderr shown to user, continues)
-- **Exit 2**: Blocking error (stderr fed to Claude for processing)
-
-**Philosophy**: Worker/hook errors exit with code 0 to prevent Windows Terminal tab accumulation. The wrapper/plugin layer handles restart logic. ERROR-level logging is maintained for diagnostics.
-
-See `private/context/claude-code/exit-codes.md` for full hook behavior matrix.
-```
-
-### Verification Checklist
-
-- [ ] `grep -n "Exit Code Strategy" CLAUDE.md` returns 1 match
-- [ ] Section appears after "File Locations" section
-- [ ] No duplicate sections added
-
-### Anti-Pattern Guards
-
-- DO NOT copy the full exit-codes.md table (keep it brief, reference the source)
-- DO NOT change actual exit code behavior in code files
-
----
-
-## Phase 3: Update Tests for New Timeout Constant
-
-### What to Implement
-
-Add test coverage for the new `POWERSHELL_COMMAND` timeout constant.
-
-### Documentation References
-
-1. Copy test pattern from `tests/hook-constants.test.ts:26-48`
-
-### Implementation Steps
-
-1. **Add test to hook-constants.test.ts** after line 42:
-   ```typescript
-   test('POWERSHELL_COMMAND timeout is 10000ms', () => {
-     expect(HOOK_TIMEOUTS.POWERSHELL_COMMAND).toBe(10000);
-   });
-   ```
-
-### Verification Checklist
-
-- [ ] `npm test -- tests/hook-constants.test.ts` passes
-- [ ] New test appears in test output
-- [ ] All 22 PowerShell parsing tests still pass
-
-### Anti-Pattern Guards
-
-- DO NOT modify PowerShell parsing tests (they test parsing, not timeouts)
-- DO NOT add integration tests for actual PowerShell execution (out of scope)
-
----
-
-## Phase 4: Final Verification
-
-### Verification Checklist
-
-1. **Build passes**: `npm run build`
-2. **All tests pass**: `npm test`
-3. **No magic numbers remain**: `grep -rn "60000" src/services/infrastructure/ProcessManager.ts` returns 0
-4. **Exit code documentation exists**: `grep -n "Exit Code Strategy" CLAUDE.md` returns 1
-5. **Constant is used**: `grep -rn "POWERSHELL_COMMAND" src/` returns multiple matches
-
-### Anti-Pattern Grep Checks
-
-- [ ] `grep -rn "timeout: 60000" src/` returns 0 matches (no hardcoded 60s timeouts in ProcessManager)
-- [ ] `grep -rn "process.exit(3)" src/` returns 0 matches (exit code 3 not used)
-
-### Commit Message Template
-
-```
-polish: extract PowerShell timeout constant and document exit code strategy
-
-- Extract magic number 60000ms to HOOK_TIMEOUTS.POWERSHELL_COMMAND (10000ms)
-- Reduce PowerShell timeout from 60s to 10s per review feedback
-- Document exit code strategy in CLAUDE.md
-- Add test coverage for new constant
-
-Addresses review feedback from PR #628
-
-Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
-```
-
----
-
-## Summary
-
-| Phase | Description | Files Changed | Verification |
-|-------|-------------|---------------|--------------|
-| 0 | Documentation Discovery | N/A | Patterns identified |
-| 1 | Extract PowerShell timeout | hook-constants.ts, ProcessManager.ts | grep + build + test |
-| 2 | Document exit strategy | CLAUDE.md | grep |
-| 3 | Add test coverage | hook-constants.test.ts | npm test |
-| 4 | Final verification | N/A | All checks pass |
-
-**Estimated Changes**: ~20 lines added/modified across 4 files
-**Risk Level**: Low (constants extraction, documentation only)
-**Breaking Changes**: None

.claude/plans/remove-worker-start-calls.md

@@ -1,394 +0,0 @@
-# Plan: Remove Worker Start Calls - In-Process Architecture
-
-## Problem Statement
-
-Current architecture has problematic spawn patterns:
-1. `hooks.json` calls `worker-service.cjs start` which spawns a daemon
-2. Spawning is buggy on Windows - **HARD RULE: NO SPAWN**
-3. `user-message` hook is deprecated
-4. `smart-install` was supposed to chain: `smart-install && stop && context`
-
-## Target Architecture
-
-**NO SPAWN - Worker runs in-process within hook command**
-
-```
-SessionStart:
-  smart-install && stop && context
-```
-
-Flow:
-1. `smart-install` - Install dependencies if needed
-2. `stop` - Kill any existing worker (clean slate)
-3. `context` - Hook starts worker IN-PROCESS, becomes the worker
-
-**Key insight:** The first hook that needs the worker **becomes** the worker. No spawn, no daemon. The hook process IS the worker process.
-
----
-
-## Current vs Target hooks.json
-
-### Current (BROKEN)
-```json
-"SessionStart": [
-  { "hooks": [
-    { "command": "node smart-install.js" },
-    { "command": "bun worker-service.cjs start" },      // REMOVE - spawn
-    { "command": "bun worker-service.cjs hook ... context" },
-    { "command": "bun worker-service.cjs hook ... user-message" }  // REMOVE - deprecated
-  ]}
-]
-```
-
-### Target
-```json
-"SessionStart": [
-  { "hooks": [
-    { "command": "node smart-install.js && bun worker-service.cjs stop && bun worker-service.cjs hook claude-code context" }
-  ]}
-]
-```
-
----
-
-## Files Involved
-
-| File | Changes |
-|------|---------|
-| `plugin/hooks/hooks.json` | Restructure to chained commands, remove start/user-message |
-| `src/services/worker-service.ts` | `hook` case: start worker in-process if not running |
-| `src/cli/handlers/*.ts` | May need adjustment for in-process execution |
-| `src/shared/worker-utils.ts` | `ensureWorkerRunning()` → adapt for in-process |
-
----
-
-## Phase 0: Documentation Discovery
-
-### Available APIs
-
-**From `src/services/infrastructure/HealthMonitor.ts`:**
-- `isPortInUse(port): Promise<boolean>`
-- `waitForHealth(port, timeoutMs): Promise<boolean>`
-- `httpShutdown(port): Promise<void>`
-
-**From `src/services/worker-service.ts`:**
-- `WorkerService` class - the actual worker
-- `stop` command - shuts down worker via HTTP
-- `--daemon` case - starts WorkerService (currently only used after spawn)
-
-**BANNED (spawn patterns):**
-- ~~`spawnDaemon()`~~ - NO SPAWN
-- ~~`fork()`~~ - NO SPAWN
-- ~~`spawn()` with detached~~ - NO SPAWN
-
-### Anti-Patterns
-- **NO SPAWN** - Hard rule, Windows buggy
-- No `restart` command - removed for same reason
-- No detached processes
-
----
-
-## Phase 1: Modify `hook` Case for In-Process Worker
-
-### Location
-`src/services/worker-service.ts:564-576`
-
-### Current Code
-```typescript
-case 'hook': {
-  const platform = process.argv[3];
-  const event = process.argv[4];
-  if (!platform || !event) {
-    console.error('Usage: claude-mem hook <platform> <event>');
-    process.exit(1);
-  }
-  const { hookCommand } = await import('../cli/hook-command.js');
-  await hookCommand(platform, event);
-  break;
-}
-```
-
-### Target Code
-```typescript
-case 'hook': {
-  const platform = process.argv[3];
-  const event = process.argv[4];
-  if (!platform || !event) {
-    console.error('Usage: claude-mem hook <platform> <event>');
-    process.exit(1);
-  }
-
-  // Check if worker already running (port in use = valid, another process has it)
-  const portInUse = await isPortInUse(port);
-  if (portInUse) {
-    // Port in use - either healthy worker or something else
-    // Proceed with hook via HTTP to existing worker
-    const { hookCommand } = await import('../cli/hook-command.js');
-    await hookCommand(platform, event);
-    break;
-  }
-
-  // Port free - start worker IN THIS PROCESS (no spawn!)
-  logger.info('SYSTEM', 'Starting worker in-process for hook');
-  const worker = new WorkerService();
-
-  // Start worker (non-blocking, returns when server listening)
-  await worker.start();
-
-  // Now execute hook logic - worker is running in this process
-  // Can call handler directly (in-process) or via HTTP to self
-  const { hookCommand } = await import('../cli/hook-command.js');
-  await hookCommand(platform, event);
-
-  // DON'T exit - this process IS the worker now
-  // Worker stays alive serving requests
-  break;
-}
-```
-
-### Key Behavior
-- If port in use → hook runs via HTTP to existing worker, then exits
-- If port free → start worker in-process, run hook, process stays alive as worker
-
-### Verification
-- [ ] Stop worker, run hook command → should start worker and stay alive
-- [ ] Worker already running, run hook command → should complete and exit
-- [ ] `lsof -i :37777` shows hook process IS the worker
-
----
-
-## Phase 2: Update hooks.json - Chained Commands
-
-### Location
-`plugin/hooks/hooks.json`
-
-### Target Structure
-```json
-{
-  "description": "Claude-mem memory system hooks",
-  "hooks": {
-    "SessionStart": [
-      {
-        "matcher": "startup|clear|compact",
-        "hooks": [
-          {
-            "type": "command",
-            "command": "node \"${CLAUDE_PLUGIN_ROOT}/scripts/smart-install.js\" && bun \"${CLAUDE_PLUGIN_ROOT}/scripts/worker-service.cjs\" stop && bun \"${CLAUDE_PLUGIN_ROOT}/scripts/worker-service.cjs\" hook claude-code context",
-            "timeout": 300
-          }
-        ]
-      }
-    ],
-    "UserPromptSubmit": [
-      {
-        "hooks": [
-          {
-            "type": "command",
-            "command": "bun \"${CLAUDE_PLUGIN_ROOT}/scripts/worker-service.cjs\" hook claude-code session-init",
-            "timeout": 60
-          }
-        ]
-      }
-    ],
-    "PostToolUse": [
-      {
-        "matcher": "*",
-        "hooks": [
-          {
-            "type": "command",
-            "command": "bun \"${CLAUDE_PLUGIN_ROOT}/scripts/worker-service.cjs\" hook claude-code observation",
-            "timeout": 120
-          }
-        ]
-      }
-    ],
-    "Stop": [
-      {
-        "hooks": [
-          {
-            "type": "command",
-            "command": "bun \"${CLAUDE_PLUGIN_ROOT}/scripts/worker-service.cjs\" hook claude-code summarize",
-            "timeout": 120
-          }
-        ]
-      }
-    ]
-  }
-}
-```
-
-### Changes Summary
-1. SessionStart: Chain `smart-install && stop && context` in single command
-2. Remove `user-message` hook (deprecated)
-3. Remove all separate `start` commands
-4. Other hooks unchanged (just hook command, auto-starts if needed)
-
-### Verification
-- [ ] JSON valid: `cat plugin/hooks/hooks.json | jq .`
-- [ ] No `start` command: `grep -c '"start"' plugin/hooks/hooks.json` = 0
-- [ ] No `user-message`: `grep -c 'user-message' plugin/hooks/hooks.json` = 0
-
----
-
-## Phase 3: Handle "Port In Use" Gracefully
-
-### Scenario
-Another process has port 37777 (not our worker). Hook should handle gracefully.
-
-### Current Behavior
-`ensureWorkerRunning()` polls for 15 seconds, then throws error.
-
-### Target Behavior
-If port in use but not healthy (not our worker):
-- Hook is "valid" - don't block Claude Code
-- Return graceful response (empty context, etc.)
-- Log warning for debugging
-
-### Location
-`src/shared/worker-utils.ts:117-141`
-
-### Changes
-```typescript
-export async function ensureWorkerRunning(): Promise<boolean> {
-  const port = getWorkerPort();
-
-  // Quick health check (2 seconds max)
-  try {
-    if (await isWorkerHealthy()) {
-      await checkWorkerVersion();
-      return true;  // Worker healthy
-    }
-  } catch (e) {
-    // Not healthy
-  }
-
-  // Port might be in use by something else
-  // Return false but don't throw - let caller decide
-  logger.warn('SYSTEM', 'Worker not healthy, hook will proceed gracefully');
-  return false;
-}
-```
-
-### Handler Updates
-Update handlers to handle `ensureWorkerRunning()` returning false:
-```typescript
-const workerReady = await ensureWorkerRunning();
-if (!workerReady) {
-  // Return graceful empty response
-  return { output: '', exitCode: HOOK_EXIT_CODES.SUCCESS };
-}
-```
-
-### Verification
-- [ ] Start non-worker process on 37777, run hook → completes gracefully
-- [ ] No 15-second hang when port blocked
-
----
-
-## Phase 4: Remove Deprecated Code
-
-### Remove `user-message` Handler (if unused elsewhere)
-- [ ] Check if `user-message.ts` is used anywhere else
-- [ ] Remove from `src/cli/handlers/index.ts` if safe
-- [ ] Consider keeping file but removing from hooks.json only
-
-### Remove `start` Command (optional)
-The `start` command in worker-service.ts can stay for manual use:
-```bash
-bun worker-service.cjs start  # Manual start if needed
-```
-But it should NOT be called from hooks.json.
-
-### Verification
-- [ ] `npm run build` succeeds
-- [ ] No references to removed handlers in hooks.json
-
----
-
-## Phase 5: Update Handler `ensureWorkerRunning()` Calls
-
-### Context
-Each handler currently calls `ensureWorkerRunning()` which polls for 15 seconds.
-
-With in-process architecture:
-- If hook started worker in-process → worker is THIS process, no HTTP needed
-- If worker already running → HTTP to existing worker
-
-### Decision
-**Keep handler calls** but modify `ensureWorkerRunning()` to:
-1. Return quickly if port is in use (assume valid)
-2. Return true if in-process worker (detect via global flag?)
-3. Graceful false return instead of throwing
-
-### Files
-- `src/cli/handlers/context.ts:15`
-- `src/cli/handlers/session-init.ts:15`
-- `src/cli/handlers/observation.ts:14`
-- `src/cli/handlers/summarize.ts:17`
-- `src/cli/handlers/file-edit.ts:15`
-
-### Verification
-- [ ] Handlers don't hang on port-in-use scenarios
-- [ ] In-process worker scenario works
-
----
-
-## Phase 6: Final Verification
-
-### Tests
-- [ ] `bun test` - All tests pass
-- [ ] `npm run build-and-sync` - Build succeeds
-
-### Manual Tests
-
-**Test 1: Clean Start**
-```bash
-bun plugin/scripts/worker-service.cjs stop
-# Start new Claude Code session
-# Verify: context hook starts worker in-process
-# Verify: lsof -i :37777 shows the hook process
-```
-
-**Test 2: Worker Already Running**
-```bash
-bun plugin/scripts/worker-service.cjs stop
-bun plugin/scripts/worker-service.cjs hook claude-code context &
-# Wait for worker to start
-bun plugin/scripts/worker-service.cjs hook claude-code observation
-# Verify: observation hook exits after completing (doesn't stay alive)
-```
-
-**Test 3: Port Blocked**
-```bash
-bun plugin/scripts/worker-service.cjs stop
-nc -l 37777 &  # Block port with netcat
-bun plugin/scripts/worker-service.cjs hook claude-code context
-# Verify: completes gracefully, doesn't hang
-kill %1  # Clean up netcat
-```
-
-**Test 4: Full Session**
-```bash
-# Start fresh Claude Code session
-# Do some work (creates observations)
-# End session (Ctrl+C or /exit)
-# Verify: summarize hook ran, observations saved
-```
-
----
-
-## Risk Assessment
-
-| Risk | Mitigation |
-|------|------------|
-| Hook stays alive forever | Expected - it's the worker now |
-| Multiple hooks compete for port | First one wins, others use HTTP |
-| Graceful shutdown on session end | Stop command in chain handles this |
-| Windows compatibility | No spawn = no Windows issues |
-
-## Rollback Plan
-
-If issues arise:
-1. Restore hooks.json with separate start commands
-2. Revert worker-service.ts hook case changes
-3. No database changes to rollback

.claude/plans/workflow-agents-integration.md

@@ -1,196 +0,0 @@
-# Plan: Integrate Workflow Agents and Commands into Claude-Mem
-
-## Executive Summary
-
-This plan integrates the `/make-plan` and `/do` orchestration workflow from `~/.claude/commands/` into the claude-mem plugin as project-level development tools.
-
-## Dependency Analysis
-
-### Commands to Copy (from `~/.claude/commands/`)
-
-| File | Purpose | Dependencies |
-|------|---------|--------------|
-| `make-plan.md` | Orchestrator for LLM-friendly phased planning | Uses Task tool with subagents |
-| `do.md` | Orchestrator for executing plans via subagents | Uses Task tool with subagents |
-| `anti-pattern-czar.md` | Error handling anti-pattern detection/fixing | Uses Read, Edit, Bash tools |
-
-### Specialized Agents Referenced
-
-The `/make-plan` and `/do` commands reference these **conceptual agent roles** (not actual agent files):
-
-| Agent Role | Referenced In | Description |
-|------------|---------------|-------------|
-| "Documentation Discovery" | make-plan.md | Fact-gathering from docs/examples |
-| "Verification" | make-plan.md, do.md | Verify implementation matches plan |
-| "Implementation" | do.md | Execute implementation tasks |
-| "Anti-pattern" | do.md | Grep for known bad patterns |
-| "Code Quality" | do.md | Review code changes |
-| "Commit" | do.md | Commit after verification passes |
-| "Branch/Sync" | do.md | Push and prepare phase handoffs |
-
-**Key Finding**: These are **role descriptions**, not separate agent files. The Task tool's `general-purpose` subagent_type executes all roles. The commands define *what* each role should do, not separate agent implementations.
-
-### Existing Project Assets
-
-Located in `.claude/`:
-- `agents/github-morning-reporter.md` - Already in project
-- `skills/version-bump/SKILL.md` - Already in project
-- No existing commands directory
-
----
-
-## Phase 0: Documentation Discovery (Complete)
-
-### Sources Consulted
-1. `/Users/alexnewman/.claude/commands/make-plan.md` (62 lines)
-2. `/Users/alexnewman/.claude/commands/do.md` (39 lines)
-3. `/Users/alexnewman/.claude/commands/anti-pattern-czar.md` (122 lines)
-4. `/Users/alexnewman/.claude/settings.json` (36 lines)
-5. `.claude/skills/CLAUDE.md` (30 lines)
-6. `.claude/agents/github-morning-reporter.md` (102 lines)
-
-### Allowed APIs/Patterns
-- **Commands**: `.claude/commands/*.md` files with `#$ARGUMENTS` placeholder for user input
-- **Skills**: `.claude/skills/<name>/SKILL.md` with YAML frontmatter (name, description)
-- **Agents**: `.claude/agents/*.md` with YAML frontmatter (name, description, model)
-
-### Anti-Patterns to Avoid
-- Skills require YAML frontmatter; commands do not
-- Commands use `#$ARGUMENTS` for input; skills/agents receive prompts differently
-- Don't create separate agent files for role descriptions - the Task tool handles routing
-
----
-
-## Phase 1: Create Commands Directory
-
-### What to Implement
-1. Create `.claude/commands/` directory
-2. Copy `make-plan.md` from `~/.claude/commands/make-plan.md`
-3. Copy `do.md` from `~/.claude/commands/do.md`
-4. Copy `anti-pattern-czar.md` from `~/.claude/commands/anti-pattern-czar.md`
-
-### Documentation References
-- Pattern: `~/.claude/commands/*.md` (source files)
-- Existing example: `.claude/skills/version-bump/SKILL.md` for claude-mem project tools
-
-### Verification Checklist
-```bash
-# Verify files exist
-ls -la .claude/commands/
-
-# Verify content matches source
-diff ~/.claude/commands/make-plan.md .claude/commands/make-plan.md
-diff ~/.claude/commands/do.md .claude/commands/do.md
-diff ~/.claude/commands/anti-pattern-czar.md .claude/commands/anti-pattern-czar.md
-
-# Verify #$ARGUMENTS placeholder exists
-grep '\$ARGUMENTS' .claude/commands/*.md
-```
-
-### Anti-Pattern Guards
-- Do NOT add YAML frontmatter to commands (they don't need it)
-- Do NOT modify the source content (copy verbatim)
-
----
-
-## Phase 2: Create CLAUDE.md Documentation
-
-### What to Implement
-Create `.claude/commands/CLAUDE.md` documenting the commands directory (following pattern from `.claude/skills/CLAUDE.md`)
-
-### Content Template
-```markdown
-# Project-Level Commands
-
-This directory contains slash commands **for developing and maintaining the claude-mem project itself**.
-
-## Commands in This Directory
-
-### /make-plan
-Orchestrator for creating LLM-friendly implementation plans in phases. Deploys subagents for documentation discovery and fact gathering.
-
-**Usage**: `/make-plan <task description>`
-
-### /do
-Orchestrator for executing plans via subagents. Deploys specialized subagents for implementation, verification, and code quality review.
-
-**Usage**: `/do <plan-file-path or inline plan>`
-
-### /anti-pattern-czar
-Interactive workflow for detecting and fixing error handling anti-patterns using the automated scanner.
-
-**Usage**: `/anti-pattern-czar`
-
-## Adding New Commands
-
-Commands are markdown files with `#$ARGUMENTS` placeholder for user input.
-```
-
-### Verification Checklist
-```bash
-# Verify file exists
-cat .claude/commands/CLAUDE.md
-```
-
----
-
-## Phase 3: Update Settings (if needed)
-
-### What to Implement
-Check if `.claude/settings.json` needs any permission updates for the new commands.
-
-### Verification Checklist
-```bash
-# Check current settings
-cat .claude/settings.json
-
-# Verify commands work by listing them
-# (After Claude Code restart, commands should appear in slash-command list)
-```
-
-### Anti-Pattern Guards
-- Do NOT add skill permissions for commands (they're different)
-- Commands don't require explicit permissions
-
----
-
-## Phase 4: Final Verification
-
-### Verification Checklist
-1. All three command files exist in `.claude/commands/`
-2. Content matches source files exactly (byte-for-byte if possible)
-3. CLAUDE.md documentation exists
-4. Git status shows new files ready for commit
-
-```bash
-# Full verification
-ls -la .claude/commands/
-wc -l .claude/commands/*.md
-git status
-```
-
-### Commit Message Template
-```
-feat: add /make-plan, /do, and /anti-pattern-czar workflow commands
-
-Add project-level orchestration commands for claude-mem development:
-- /make-plan: Create LLM-friendly implementation plans in phases
-- /do: Execute plans via coordinated subagents
-- /anti-pattern-czar: Detect and fix error handling anti-patterns
-
-These commands enable structured, agent-driven development workflows.
-```
-
----
-
-## Summary
-
-**Files to Create**:
-1. `.claude/commands/make-plan.md` (copy from ~/.claude/commands/)
-2. `.claude/commands/do.md` (copy from ~/.claude/commands/)
-3. `.claude/commands/anti-pattern-czar.md` (copy from ~/.claude/commands/)
-4. `.claude/commands/CLAUDE.md` (new documentation)
-
-**No Agent Files Needed**: The "agents" referenced in make-plan.md and do.md are role descriptions, not separate files. The Task tool's built-in subagent types handle execution.
-
-**Confidence**: High - analysis complete with full source file reads.

.github/workflows/claude-code-review.yml

@@ -27,7 +27,7 @@ jobs:
 
     steps:
       - name: Checkout repository
-        uses: actions/checkout@v4
+        uses: actions/checkout@v6
         with:
           fetch-depth: 1
 

.github/workflows/claude.yml

@@ -26,7 +26,7 @@ jobs:
       actions: read # Required for Claude to read CI results on PRs
     steps:
       - name: Checkout repository
-        uses: actions/checkout@v4
+        uses: actions/checkout@v6
         with:
           fetch-depth: 1
 

.github/workflows/convert-feature-requests.yml

@@ -26,7 +26,7 @@ jobs:
     steps:
       - name: Get issue details and create discussion
         id: discussion
-        uses: actions/github-script@v7
+        uses: actions/github-script@v8
         with:
           script: |
             // Get issue details
@@ -87,7 +87,7 @@ jobs:
             }
 
       - name: Comment on issue
-        uses: actions/github-script@v7
+        uses: actions/github-script@v8
         with:
           script: |
             const issueNumber = ${{ steps.discussion.outputs.issue_number }};
@@ -105,7 +105,7 @@ jobs:
             console.log(`Added comment to issue #${issueNumber}`);
 
       - name: Close and lock issue
-        uses: actions/github-script@v7
+        uses: actions/github-script@v8
         with:
           script: |
             const issueNumber = ${{ steps.discussion.outputs.issue_number }};

.github/workflows/deploy-install-scripts.yml

@@ -0,0 +1,29 @@
+name: Deploy Install Scripts
+
+on:
+  push:
+    branches: [main]
+    paths:
+      - 'openclaw/install.sh'
+      - 'install/**'
+  workflow_dispatch:
+
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Copy install scripts to deploy directory
+        run: |
+          mkdir -p install/public
+          cp openclaw/install.sh install/public/openclaw.sh
+
+      - name: Deploy to Vercel
+        uses: amondnet/vercel-action@v25
+        with:
+          vercel-token: ${{ secrets.VERCEL_TOKEN }}
+          vercel-org-id: ${{ secrets.VERCEL_ORG_ID }}
+          vercel-project-id: ${{ secrets.VERCEL_PROJECT_ID }}
+          vercel-args: '--prod'
+          working-directory: ./install

.github/workflows/npm-publish.yml

@@ -0,0 +1,21 @@
+name: Publish to npm
+
+on:
+  push:
+    tags:
+      - 'v*'
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+          registry-url: 'https://registry.npmjs.org'
+      - run: npm install --ignore-scripts
+      - run: npm run build
+      - run: npm publish
+        env:
+          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}

.github/workflows/summary.yml

@@ -14,11 +14,11 @@ jobs:
 
     steps:
       - name: Checkout repository
-        uses: actions/checkout@v4
+        uses: actions/checkout@v6
 
       - name: Run AI inference
         id: inference
-        uses: actions/ai-inference@v1
+        uses: actions/ai-inference@v2
         with:
           prompt: |
             Summarize the following GitHub issue in one paragraph:

.gitignore

@@ -1,6 +1,8 @@
 datasets/
 node_modules/
 dist/
+!installer/dist/
+**/_tree-sitter/
 *.log
 .DS_Store
 .env
@@ -11,12 +13,15 @@ dist/
 .claude/settings.local.json
 .claude/agents/
 .claude/skills/
+.claude/plans/
+.claude/worktrees/
 plugin/data/
 plugin/data.backup/
 package-lock.json
 bun.lock
 private/
 datasets/
+Auto Run Docs/
 
 # Generated UI files (built from viewer-template.html)
 src/ui/viewer.html

.markdownlint.json

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

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

Auto Run Docs/Bigph00t-PRs/Phase-01-Merge-PR-745-Isolated-Credentials.md

@@ -1,82 +0,0 @@
-# Phase 01: Merge PR #745 - Isolated Credentials
-
-**PR:** https://github.com/thedotmack/claude-mem/pull/745
-**Branch:** `fix/isolated-credentials-733`
-**Status:** Has conflicts, needs rebase
-**Review:** Approved by bayanoj330-dev
-**Priority:** HIGH - Foundation for credential isolation, required by PR #847
-
-## Summary
-
-Fixes API key hijacking issue (#733) where SDK would use `ANTHROPIC_API_KEY` from random project `.env` files instead of Claude Code CLI subscription billing.
-
-**Root Cause:** The SDK's `query()` function inherits from `process.env` when no `env` option is passed.
-
-**Solution:** Centralized credential management via `~/.claude-mem/.env` with `EnvManager.ts`.
-
-## Files Changed
-
-| File | Change |
-|------|--------|
-| `src/shared/EnvManager.ts` | NEW: Centralized credential storage and isolated env builder |
-| `src/services/worker/SDKAgent.ts` | Pass isolated env to SDK `query()` |
-| `src/services/worker/GeminiAgent.ts` | Use `getCredential()` instead of `process.env` |
-| `src/services/worker/OpenRouterAgent.ts` | Use `getCredential()` instead of `process.env` |
-| `src/shared/SettingsDefaultsManager.ts` | Add `CLAUDE_MEM_CLAUDE_AUTH_METHOD` setting |
-
-## Dependencies
-
-- **None** - This is a foundation PR
-
-## Tasks
-
-- [x] Checkout PR branch `fix/isolated-credentials-733` and rebase onto main to resolve conflicts
-  - ✓ Resolved 4 conflicts (3 build artifacts, 1 source file)
-  - ✓ Merged both main's zombie process cleanup and PR's isolated credentials into SDKAgent.ts
-  - ✓ Commit 006ff401 now sits on top of main (aedee33c)
-- [x] Review `EnvManager.ts` implementation for security and correctness
-  - ✓ **Security Assessment - PASS**:
-    - Credentials stored in user-private location (`~/.claude-mem/.env`) with standard file permissions
-    - `buildIsolatedEnv()` explicitly excludes `process.env` credentials, preventing Issue #733
-    - Only whitelisted essential system vars (PATH, HOME, NODE_ENV, etc.) are passed to subprocesses
-    - Quote stripping in `.env` parser handles both single and double quotes correctly
-    - No credential logging - keys are never written to logs
-  - ✓ **Correctness Assessment - PASS**:
-    - `loadClaudeMemEnv()` gracefully returns empty object if `.env` doesn't exist (enables CLI billing fallback)
-    - `saveClaudeMemEnv()` preserves existing keys and creates directory if needed
-    - `getCredential()` used correctly by GeminiAgent and OpenRouterAgent
-    - SDKAgent passes `isolatedEnv` to SDK query() options, blocking random API key pollution
-    - Auth method description properly reflects whether CLI billing or explicit API key is used
-  - ✓ **Code Quality - GOOD**:
-    - Well-documented with JSDoc comments explaining Issue #733 fix
-    - Type-safe with `ClaudeMemEnv` interface
-    - Essential vars list covers cross-platform needs (Windows, Linux, macOS)
-- [x] Verify build succeeds after rebase
-  - ✓ Build completed successfully: worker-service (1788KB), mcp-server (332KB), context-generator (61KB), viewer UI
-- [x] Run test suite to ensure no regressions
-  - ✓ Fixed console.log/console.error usage in EnvManager.ts (replaced with logger calls per project standards)
-  - ✓ All 797 tests pass (0 fail, 3 skip)
-- [x] Merge PR #745 to main with admin override if needed
-  - ✓ Merged with `--no-ff` to preserve commit history
-  - ✓ Commit 486570d2 on main includes all 4 PR commits
-  - ✓ GitHub branch protection bypassed with admin privileges
-  - ✓ PR #745 auto-closed by GitHub upon detecting commits in main
-  - ✓ Build verified successful after merge
-- [x] Verify auth method shows "Claude Code CLI (subscription billing)" in logs after merge
-  - ✓ Rebuilt and synced local code (v9.0.14 release predated PR merge, so needed fresh build)
-  - ✓ Restarted worker with PR #745 code
-  - ✓ Confirmed log output: `authMethod=Claude Code CLI (subscription billing)`
-  - ✓ Verified `getAuthMethodDescription()` correctly detects no API key in `~/.claude-mem/.env`
-
-## Verification
-
-```bash
-# After merge, check logs for correct auth method
-grep -i "authMethod" ~/.claude-mem/logs/*.log | tail -5
-```
-
-## Notes
-
-- This PR creates the `EnvManager.ts` module that PR #847 depends on
-- The isolated env approach ensures SDK subprocess never sees random API keys from parent process
-- If no `ANTHROPIC_API_KEY` is in `~/.claude-mem/.env`, Claude Code CLI billing is used (default)

Auto Run Docs/Bigph00t-PRs/Phase-02-Merge-PR-820-Health-Check-Endpoint.md

@@ -1,57 +0,0 @@
-# Phase 02: Merge PR #820 - Health Check Endpoint Fix
-
-**PR:** https://github.com/thedotmack/claude-mem/pull/820
-**Branch:** `fix/health-check-endpoint-811`
-**Status:** Has conflicts, needs rebase
-**Review:** Approved by bayanoj330-dev
-**Priority:** HIGH - Fixes 15-second timeout issue affecting all users
-
-## Summary
-
-Fixes the "Worker did not become ready within 15 seconds" timeout issue by changing health check functions from `/api/readiness` to `/api/health`.
-
-**Root Cause:** `isWorkerHealthy()` and `waitForHealth()` were using `/api/readiness` which returns 503 until full initialization completes (including MCP connection which can take 5+ minutes). Hooks only have 15 seconds timeout.
-
-**Solution:** Use `/api/health` (liveness check) which returns 200 as soon as HTTP server is listening.
-
-## Files Changed
-
-| File | Change |
-|------|--------|
-| `src/shared/worker-utils.ts` | Change `/api/readiness` → `/api/health` in `isWorkerHealthy()` |
-| `src/services/infrastructure/HealthMonitor.ts` | Change `/api/readiness` → `/api/health` in `waitForHealth()` |
-| `tests/infrastructure/health-monitor.test.ts` | Update test to expect `/api/health` |
-
-## Dependencies
-
-- **None** - Independent fix
-
-## Fixes Issues
-
-- #811
-- #772
-- #729
-
-## Tasks
-
-- [x] Checkout PR branch `fix/health-check-endpoint-811` and rebase onto main to resolve conflicts *(Completed: Rebased successfully - build artifact conflicts resolved by accepting main and will rebuild)*
-- [x] Review the endpoint change logic in `worker-utils.ts` and `HealthMonitor.ts` *(Completed: Logic is sound - both files use `/api/health` with proper JSDoc explaining the liveness vs readiness distinction)*
-- [x] Verify build succeeds after rebase *(Completed: Build succeeded - all hooks, worker service, MCP server, context generator, and React viewer built successfully)*
-- [x] Run health monitor tests: `npm test -- tests/infrastructure/health-monitor.test.ts` *(Completed: All 14 tests pass with 24 expect() calls)*
-- [x] Merge PR #820 to main *(Completed: Fast-forward merge from fix/health-check-endpoint-811 to main, pushed to origin)*
-- [x] Manual verification: Kill worker and start fresh session - should not see 15-second timeout *(Completed: Worker health endpoint responds in ~12ms, no timeout errors in logs, both worker-utils.ts and HealthMonitor.ts correctly use /api/health)*
-
-## Verification
-
-```bash
-# After merge, verify hooks work during MCP initialization
-# Start a fresh session and observe logs
-tail -f ~/.claude-mem/logs/worker.log | grep -i "health"
-```
-
-## Notes
-
-- This is a quick fix with minimal code changes
-- The `/api/health` endpoint returns 200 as soon as Express is listening
-- Background initialization continues after health check passes
-- Related to PR #774 which had the same fix but has merge conflicts

Auto Run Docs/Bigph00t-PRs/Phase-03-Merge-PR-827-Bun-Runner.md

@@ -1,76 +0,0 @@
-# Phase 03: Merge PR #827 - Bun Runner for Fresh Install
-
-**PR:** https://github.com/thedotmack/claude-mem/pull/827
-**Branch:** `fix/fresh-install-bun-path-818`
-**Status:** Merged to main (commit 99138203)
-**Review:** Approved by bayanoj330-dev
-**Priority:** MEDIUM - Fixes fresh installation issues
-
-## Summary
-
-Fixes the fresh install issue where worker fails to start because Bun isn't in PATH yet after `smart-install.js` installs it.
-
-**Root Cause:** On fresh installations:
-1. `smart-install.js` installs Bun to `~/.bun/bin/bun`
-2. Bun isn't in current shell's PATH until terminal restart
-3. Hooks try to run `bun ...` directly and fail
-4. Worker never starts, database never created
-
-**Solution:** Introduce `bun-runner.js` - a Node.js script that finds Bun in common install locations (not just PATH) and runs commands with it.
-
-## Files Changed
-
-| File | Change |
-|------|--------|
-| `plugin/scripts/bun-runner.js` | NEW: Script to find and run Bun |
-| `plugin/hooks/hooks.json` | Use `node bun-runner.js` instead of direct `bun` calls |
-
-## Dependencies
-
-- **None** - Independent fix
-
-## Fixes Issues
-
-- #818
-
-## Bun Search Locations
-
-The bun-runner checks these locations in order:
-- PATH (via `which`/`where`)
-- `~/.bun/bin/bun` (default install location)
-- `/usr/local/bin/bun`
-- `/opt/homebrew/bin/bun` (macOS Homebrew)
-- `/home/linuxbrew/.linuxbrew/bin/bun` (Linuxbrew)
-- Windows: `%LOCALAPPDATA%\bun\bin\bun.exe` with fallback
-
-## Tasks
-
-- [x] Checkout PR branch `fix/fresh-install-bun-path-818` and rebase onto main to resolve conflicts
-  - Resolved hooks.json conflict: preserved Setup hook from main, applied bun-runner.js pattern to all hook commands
-- [x] Review `bun-runner.js` for correctness across platforms
-  - ESM imports work (plugin has `"type": "module"`), PATH check uses platform-correct `which`/`where`, covers standard install paths for macOS/Linux/Windows
-- [x] Verify hooks.json uses correct `node bun-runner.js` pattern
-  - All 9 hook commands use `node bun-runner.js`, zero direct `bun` calls remain
-- [x] Verify build succeeds after rebase
-  - `npm run build-and-sync` completed successfully, bun-runner.js synced to marketplace
-- [x] Merge PR #827 to main
-  - Merged with `--no-ff`, pushed to origin, PR #827 closed
-- [x] Test on fresh install (uninstall claude-mem, reinstall) to verify Bun is found
-  - `node plugin/scripts/bun-runner.js --version` returns Bun 1.2.20 successfully
-
-## Verification
-
-```bash
-# After merge, verify bun-runner finds Bun
-node plugin/scripts/bun-runner.js --version
-
-# Check hooks.json uses bun-runner
-grep -i "bun-runner" plugin/hooks/hooks.json
-```
-
-## Notes
-
-- This is a surgical fix that doesn't change core functionality
-- All hooks now go through the Node.js bun-runner script
-- Cross-platform: Linux, macOS, Windows
-- The bun-runner approach is more robust than relying on PATH

Auto Run Docs/Initiation/Phase-01-Merge-PR-856-Zombie-Observer-Fix.md

@@ -1,65 +0,0 @@
-# Phase 01: Test and Merge PR #856 - Zombie Observer Fix
-
-PR #856 adds idle timeout to `SessionQueueProcessor` to prevent zombie observer processes. This is the most mature PR with existing test coverage, passing CI, and no merge conflicts. By the end of this phase, the fix will be merged to main and the improvement will be live.
-
-## Tasks
-
-- [x] Checkout and verify PR #856:
-  - `git fetch origin fix/observer-idle-timeout`
-  - `git checkout fix/observer-idle-timeout`
-  - Verify the branch is up to date with origin
-  - ✅ Branch verified up to date with origin (pulled 4 new files: PR-SHIPPING-REPORT.md, package.json updates, hooks.json updates, setup.sh)
-
-- [x] Run the full test suite to confirm all tests pass:
-  - `npm test`
-  - Specifically verify the 11 SessionQueueProcessor tests pass
-  - Report any failures
-  - ✅ Full test suite passes: 797 pass, 3 skip (pre-existing), 0 fail
-  - ✅ All 11 SessionQueueProcessor tests pass: 11 pass, 0 fail, 20 expect() calls
-
-- [x] Run the build to confirm compilation succeeds:
-  - `npm run build`
-  - Verify no TypeScript errors
-  - Verify all artifacts are generated
-  - ✅ Build completed successfully with no TypeScript errors
-  - ✅ All artifacts generated:
-    - worker-service.cjs (1786.80 KB)
-    - mcp-server.cjs (332.41 KB)
-    - context-generator.cjs (61.57 KB)
-    - viewer-bundle.js and viewer.html
-
-- [x] Code review the changes for correctness:
-  - Read `src/services/queue/SessionQueueProcessor.ts` and verify:
-    - `IDLE_TIMEOUT_MS` is set to 3 minutes (180000ms)
-    - `waitForMessage()` accepts timeout parameter
-    - `lastActivityTime` is reset on spurious wakeup (race condition fix)
-    - Graceful exit logs with `thresholdMs` parameter
-  - Read `tests/services/queue/SessionQueueProcessor.test.ts` and verify test coverage
-  - ✅ Code review complete - all requirements verified:
-    - Line 6: `IDLE_TIMEOUT_MS = 3 * 60 * 1000` (180000ms)
-    - Line 90: `waitForMessage(signal: AbortSignal, timeoutMs: number = IDLE_TIMEOUT_MS)`
-    - Line 63: `lastActivityTime = Date.now()` on spurious wakeup with comment
-    - Lines 54-58: Logger includes `thresholdMs: IDLE_TIMEOUT_MS` parameter
-    - 11 test cases covering idle timeout, abort signal, message events, cleanup, errors, and conversion
-
-- [x] Merge PR #856 to main:
-  - `git checkout main`
-  - `git pull origin main`
-  - `gh pr merge 856 --squash --delete-branch`
-  - Verify merge succeeded
-  - ✅ PR #856 successfully merged to main on 2026-02-05T00:31:24Z
-  - ✅ Merge commit: 7566b8c650d670d7f06f0b4b321aeb56e4d3f109
-  - ✅ Branch fix/observer-idle-timeout deleted
-  - Note: Used --admin flag to bypass failing claude-review CI check (GitHub App not installed - configuration issue, not code issue)
-
-- [x] Run post-merge verification:
-  - `git pull origin main`
-  - `npm test` to confirm tests still pass on main
-  - `npm run build` to confirm build still works
-  - ✅ Main branch is up to date with origin
-  - ✅ Full test suite passes: 797 pass, 3 skip, 0 fail, 1491 expect() calls
-  - ✅ Build completed successfully with all artifacts generated:
-    - worker-service.cjs (1786.80 KB)
-    - mcp-server.cjs (332.41 KB)
-    - context-generator.cjs (61.57 KB)
-    - viewer-bundle.js and viewer.html

Auto Run Docs/Initiation/Phase-02-Merge-PR-722-In-Process-Worker.md

@@ -1,91 +0,0 @@
-# Phase 02: Resolve Conflicts and Merge PR #722 - In-Process Worker Architecture
-
-PR #722 replaces spawn-based worker startup with in-process architecture. Hook processes become the worker when port 37777 is free, eliminating Windows spawn issues. This PR has merge conflicts that must be resolved before merging.
-
-## Tasks
-
-- [x] Checkout PR #722 and assess conflict scope:
-  - `git fetch origin bugfix/claude-md-index`
-  - `git checkout bugfix/claude-md-index`
-  - `git merge main` to see conflicts
-  - List all conflicting files
-
-  **Completed 2026-02-04:** Identified 8 conflicting files:
-  - `docs/CLAUDE.md` (delete/modify - accepted main)
-  - `plugin/CLAUDE.md` (delete/modify - accepted main)
-  - `plugin/hooks/hooks.json` (content conflict - merged both features)
-  - `plugin/scripts/mcp-server.cjs` (build artifact - accepted main)
-  - `plugin/scripts/worker-service.cjs` (build artifact - accepted main)
-  - `src/services/domain/CLAUDE.md` (delete/modify - accepted main)
-  - `src/services/sqlite/CLAUDE.md` (delete/modify - accepted main)
-  - `src/utils/claude-md-utils.ts` (content conflict - preserved #794 fix from main)
-
-- [x] Resolve merge conflicts in each affected file:
-  - For each conflict, understand both sides:
-    - Main branch changes (likely from PR #856 merge)
-    - PR #722 changes (in-process worker architecture)
-  - Preserve both sets of functionality where possible
-  - Key files likely affected:
-    - `src/services/worker-service.ts`
-    - `src/services/queue/SessionQueueProcessor.ts`
-    - `plugin/hooks/hooks.json`
-
-  **Completed 2026-02-04:** All conflicts resolved:
-  - CLAUDE.md files: Accepted main's versions (project uses these for context)
-  - Build artifacts: Accepted main's versions (will be regenerated by build)
-  - hooks.json: Combined PR #722's chained command (smart-install + stop + hook) with main's dual-hook structure
-  - claude-md-utils.ts: Preserved main's #794 fix for empty CLAUDE.md handling
-
-- [x] Run tests after conflict resolution:
-  - `npm test`
-  - All tests must pass (761+ expected)
-  - Report any failures with details
-
-  **Completed 2026-02-04:** All 797 tests passed (3 skipped, 0 failed). 1490 expect() calls across 46 files in 9.99s.
-
-- [x] Run build after conflict resolution:
-  - `npm run build`
-  - Verify no TypeScript errors
-  - Verify all artifacts are generated
-
-  **Completed 2026-02-04:** Build succeeded with no errors. All artifacts generated:
-  - worker-service.cjs (1786.77 KB)
-  - mcp-server.cjs (332.41 KB)
-  - context-generator.cjs (61.57 KB)
-  - viewer.html and viewer-bundle.js
-
-- [x] Code review the in-process worker changes:
-  - Verify `worker-service.ts` hook case starts WorkerService in-process when port free
-  - Verify `hook-command.ts` has `skipExit` option
-  - Verify `hooks.json` uses single chained command
-  - Verify `worker-utils.ts` `ensureWorkerRunning()` returns boolean
-
-  **Completed 2026-02-04:** All review criteria verified:
-  - `worker-service.ts` (lines 638-665): Hook case checks `!portInUse`, creates `new WorkerService()`, calls `start()`, sets `startedWorkerInProcess = true`, uses `break` (not exit) to keep process alive
-  - `hook-command.ts` (lines 6-9, 24-27): `HookCommandOptions` interface has `skipExit?: boolean`, checked before `process.exit()`, returns exit code when skipped
-  - `hooks.json` (line 22): SessionStart uses chained command `smart-install.js && worker stop && worker hook claude-code context`
-  - `worker-utils.ts` (lines 117-135): `ensureWorkerRunning(): Promise<boolean>` returns true if healthy, false otherwise
-
-- [x] Commit conflict resolution and push:
-  - `git add .`
-  - `git commit -m "chore: resolve merge conflicts with main"`
-  - `git push origin bugfix/claude-md-index`
-
-  **Completed 2026-02-04:** Conflict resolution was committed (34b7e13a) and pushed to origin. Verified commit exists in remote branch history.
-
-- [x] Merge PR #722 to main:
-  - Wait for CI to pass after push
-  - `gh pr merge 722 --squash --delete-branch`
-  - Verify merge succeeded
-
-  **Completed 2026-02-04:** PR #722 merged using admin override (claude-review check stuck - same Claude Code GitHub App issue as Phase 01). Merge commit: 4df9f61347407f272fb72eb78b8e500ad1212703. Branch `bugfix/claude-md-index` auto-deleted.
-
-- [x] Run post-merge verification:
-  - `git checkout main && git pull origin main`
-  - `npm test` to confirm tests pass on main
-  - `npm run build` to confirm build works
-
-  **Completed 2026-02-04:** Post-merge verification successful:
-  - Checked out main and pulled latest (already up to date with origin/main)
-  - Tests: 797 passed, 3 skipped, 0 failed (1490 expect() calls across 46 files in 9.94s)
-  - Build: Succeeded with all artifacts generated (worker-service.cjs 1786.77 KB, mcp-server.cjs 332.41 KB, context-generator.cjs 61.57 KB, viewer.html and viewer-bundle.js)

Auto Run Docs/Initiation/Phase-03-Merge-PR-700-Windows-Popup-Fix.md

@@ -1,54 +0,0 @@
-# Phase 03: Resolve Conflicts and Merge PR #700 - Windows Terminal Popup Fix
-
-PR #700 eliminates Windows Terminal popups by removing spawn-based daemon startup. The worker `start` command now becomes daemon directly instead of spawning a child process. This PR has merge conflicts and may have significant overlap with PR #722 (in-process worker).
-
-## Tasks
-
-- [ ] Checkout PR #700 and assess conflict scope:
-  - `git fetch origin bugfix/spawners`
-  - `git checkout bugfix/spawners`
-  - `git merge main` to see conflicts
-  - List all conflicting files
-  - Assess if changes overlap significantly with already-merged PR #722
-
-- [ ] Evaluate if PR #700 is still needed:
-  - PR #722 (in-process worker) may have already addressed the same Windows spawn issues
-  - Compare the changes in both PRs
-  - If #722 fully supersedes #700, close #700 with explanation
-  - Otherwise proceed with conflict resolution
-
-- [ ] If proceeding, resolve merge conflicts:
-  - Key files likely affected:
-    - `src/services/worker-service.ts` (daemon startup changes)
-    - `src/services/sync/ChromaSync.ts` (windowsHide removal)
-    - `plugin/hooks/hooks.json` (command changes)
-  - Preserve functionality from main while adding non-spawn daemon behavior
-
-- [ ] Run tests after conflict resolution:
-  - `npm test`
-  - All tests must pass
-  - Report any failures with details
-
-- [ ] Run build after conflict resolution:
-  - `npm run build`
-  - Verify no TypeScript errors
-
-- [ ] Code review the Windows-specific changes:
-  - Verify worker `start` command becomes daemon directly (no child spawn)
-  - Verify `restart` command removal (users do stop then start)
-  - Verify windowsHide removal from ChromaSync
-
-- [ ] Commit conflict resolution and push:
-  - `git add .`
-  - `git commit -m "chore: resolve merge conflicts with main"`
-  - `git push origin bugfix/spawners`
-
-- [ ] Merge PR #700 to main:
-  - Wait for CI to pass after push
-  - `gh pr merge 700 --squash --delete-branch`
-  - Verify merge succeeded
-
-- [ ] Run post-merge verification:
-  - `git checkout main && git pull origin main`
-  - `npm test` to confirm tests pass
-  - `npm run build` to confirm build works

Auto Run Docs/Initiation/Phase-04-Merge-PR-657-CLI-Commands.md

@@ -1,54 +0,0 @@
-# Phase 04: Resolve Conflicts and Merge PR #657 - CLI Generate/Clean Commands
-
-PR #657 adds `claude-mem generate` and `claude-mem clean` CLI commands with cross-platform support. It also fixes validation gaps that caused deleted folders to be recreated from stale DB records, and adds automatic shell alias installation. This PR has merge conflicts.
-
-## Tasks
-
-- [ ] Checkout PR #657 and assess conflict scope:
-  - `git fetch origin bugfix/jan10-bug-2`
-  - `git checkout bugfix/jan10-bug-2`
-  - `git merge main` to see conflicts
-  - List all conflicting files
-
-- [ ] Resolve merge conflicts:
-  - Key files likely affected:
-    - `src/services/worker-service.ts` (generate/clean command cases)
-    - `plugin/scripts/smart-install.js` (CLI installation)
-  - Preserve all existing functionality while adding CLI commands
-
-- [ ] Run tests after conflict resolution:
-  - `npm test`
-  - All tests must pass
-  - Report any failures with details
-
-- [ ] Run build after conflict resolution:
-  - `npm run build`
-  - Verify no TypeScript errors
-
-- [ ] Test the CLI commands manually:
-  - `bun plugin/scripts/worker-service.cjs generate --dry-run`
-  - `bun plugin/scripts/worker-service.cjs clean --dry-run`
-  - Both should exit with code 0
-  - Review output for sensible behavior
-
-- [ ] Code review the CLI implementation:
-  - Verify `src/cli/claude-md-commands.ts` exports generate/clean functions
-  - Verify validation fixes in `regenerateFolder()` (folder existence check)
-  - Verify path traversal prevention
-  - Verify cross-platform path handling (`toDbPath()`, `toFsPath()`)
-
-- [ ] Commit conflict resolution and push:
-  - `git add .`
-  - `git commit -m "chore: resolve merge conflicts with main"`
-  - `git push origin bugfix/jan10-bug-2`
-
-- [ ] Merge PR #657 to main:
-  - Wait for CI to pass after push
-  - `gh pr merge 657 --squash --delete-branch`
-  - Verify merge succeeded
-
-- [ ] Run post-merge verification:
-  - `git checkout main && git pull origin main`
-  - `npm test` to confirm tests pass
-  - `npm run build` to confirm build works
-  - Verify CLI commands still work: `bun plugin/scripts/worker-service.cjs generate --dry-run`

Auto Run Docs/Initiation/Phase-05-Merge-PR-863-Ragtime-Email.md

@@ -1,46 +0,0 @@
-# Phase 05: Test and Merge PR #863 - Ragtime Email Investigation
-
-PR #863 adds email investigation mode via `CLAUDE_MEM_MODE` environment variable. Each file is processed in a new session with context managed by Claude-mem hooks. It includes configurable transcript cleanup to prevent buildup. This PR has no merge conflicts and CI is passing.
-
-## Tasks
-
-- [ ] Checkout and verify PR #863:
-  - `git fetch origin claude/setup-ragtime-epstein-analysis-JApkL`
-  - `git checkout claude/setup-ragtime-epstein-analysis-JApkL`
-  - Verify the branch is up to date with origin
-
-- [ ] Rebase onto main to incorporate previous PR merges:
-  - `git rebase main`
-  - If conflicts arise, resolve them
-  - Push with `git push --force-with-lease origin claude/setup-ragtime-epstein-analysis-JApkL`
-
-- [ ] Run the full test suite:
-  - `npm test`
-  - All tests must pass
-  - Report any failures
-
-- [ ] Run the build:
-  - `npm run build`
-  - Verify no TypeScript errors
-
-- [ ] Code review the ragtime implementation:
-  - Understand the `CLAUDE_MEM_MODE` environment variable usage
-  - Review session-per-file processing approach
-  - Review transcript cleanup configuration (default 24h)
-  - Verify environment variable configuration for paths and settings
-
-- [ ] Evaluate if this feature belongs in main:
-  - This appears to be an experimental/specialized feature
-  - Consider if it should be merged or kept as experimental branch
-  - If appropriate for main, proceed with merge
-  - If experimental, document status and skip merge
-
-- [ ] If proceeding, merge PR #863 to main:
-  - `gh pr merge 863 --squash --delete-branch`
-  - Verify merge succeeded
-
-- [ ] Run final verification:
-  - `git checkout main && git pull origin main`
-  - `npm test` to confirm all tests pass
-  - `npm run build` to confirm build works
-  - Verify all 5 PRs are now merged

Auto Run Docs/PR-Triage/PR-Triage-01.md

@@ -1,33 +0,0 @@
-# Phase 01: Close Stale/Already-Addressed PRs
-
-These PRs fix issues that have already been resolved in released versions. Close each with a comment explaining which version addressed the fix.
-
-- [x] Close PR #820 (`fix: use /api/health instead of /api/readiness` by @bigph00t) with comment: "This fix was merged in v9.0.16 — see the changelog entry for 'Fix Worker Startup Timeout (#811, #772, #729)'. The health check endpoint was switched from `/api/readiness` to `/api/health` in that release. Closing as already addressed. Thank you for the contribution!" Run: `gh pr close 820 --comment "Already addressed in v9.0.16 — health check endpoint switched from /api/readiness to /api/health. See changelog. Thank you for the contribution!"`
-  - ✅ Closed 2026-02-05 by Claude-Mem PRs agent
-
-- [x] Close PR #774 (`fix: use /api/health instead of /api/readiness` by @rajivsinclair) — same fix as #820, already shipped in v9.0.16. Run: `gh pr close 774 --comment "Already addressed in v9.0.16 (same fix as PR #820 which was merged). Health checks now use /api/health. Thank you!"`
-  - ✅ Closed 2026-02-05 by Claude-Mem PRs agent
-
-- [x] Close PR #773 (`fix: use /api/health instead of /api/readiness` by @rajivsinclair) — same fix as #820/#774, already shipped in v9.0.16. Run: `gh pr close 773 --comment "Already addressed in v9.0.16 (same fix as PR #820 which was merged). Health checks now use /api/health. Thank you!"`
-  - ✅ Closed 2026-02-05 by Claude-Mem PRs agent
-
-- [x] Close PR #861 (`fix: add idle timeout with abort to prevent zombie observer processes` by @bigph00t) — v9.0.13 shipped zombie observer prevention with 3-minute idle timeout. Run: `gh pr close 861 --comment "Already addressed in v9.0.13 — 'Zombie Observer Prevention (#856)' added 3-minute idle timeout with race condition fix and 11 tests. Thank you for the contribution!"`
-  - ✅ Closed 2026-02-05 by Claude-Mem PRs agent
-
-- [x] Close PR #848 (`fix: Kill duplicate observer processes to prevent zombie accumulation` by @influenist) — v9.0.13 addresses zombie observers. Run: `gh pr close 848 --comment "Already addressed in v9.0.13 — zombie observer prevention with idle timeout. Thank you!"`
-  - ✅ Closed 2026-02-05 by Claude-Mem PRs agent
-
-- [x] Close PR #735 (`fix: strip ANTHROPIC_API_KEY for Claude Code subscribers` by @shyal) — v9.0.15 shipped isolated credentials, sourcing exclusively from ~/.claude-mem/.env. Run: `gh pr close 735 --comment "Already addressed in v9.0.15 — 'Isolated Credentials (#745)' now sources credentials exclusively from ~/.claude-mem/.env with whitelisted env vars. Thank you!"`
-  - ✅ Closed 2026-02-05 by Claude-Mem PRs agent
-
-- [x] Close PR #840 (`fix(windows): replace WMIC with PowerShell Start-Process` by @bivlked) — v9.0.2 already replaced WMIC with PowerShell. Run: `gh pr close 840 --comment "Already addressed in v9.0.2 — replaced deprecated WMIC commands with PowerShell Get-Process and Get-CimInstance. Thank you!"`
-  - ✅ Closed 2026-02-05 by Claude-Mem PRs agent
-
-- [x] Close PR #933 (`fix(windows): replace deprecated wmic worker spawn with child_process spawn` by @jayvenn21) — same WMIC issue, fixed in v9.0.2. Run: `gh pr close 933 --comment "Already addressed in v9.0.2 — WMIC replacement with PowerShell commands. Thank you!"`
-  - ✅ Closed 2026-02-05 by Claude-Mem PRs agent
-
-- [x] Close PR #700 (`fix(#681): eliminate Windows Terminal popup by removing spawn-based daemon` by @thedotmack) — fixed in v9.0.6 (Windows console popup fix). Run: `gh pr close 700 --comment "Already addressed in v9.0.6 — Windows console popups eliminated with WMIC-based detached process spawning. Closing as resolved."`
-  - ✅ Closed 2026-02-05 by Claude-Mem PRs agent
-
-- [x] Close PR #521 (`fix: implement two-stage readiness to prevent fresh install timeout` by @seanGSISG) — v9.0.16 switched to /api/health and v9.0.17 added bun-runner.js for fresh install PATH resolution. Run: `gh pr close 521 --comment "Already addressed in v9.0.16 (health check fix) and v9.0.17 (bun-runner.js for fresh install Bun PATH resolution). Thank you!"`
-  - ✅ Closed 2026-02-05 by Claude-Mem PRs agent

Auto Run Docs/PR-Triage/PR-Triage-02.md

@@ -1,31 +0,0 @@
-# Phase 02: Close Junk/Suspicious PRs & Duplicate PRs
-
-## Junk/Suspicious PRs
-
-- [x] Close PR #546 (title: "main" by @delorenj) — garbage PR with branch name `main`, 17 files changed with no coherent purpose. Run: `gh pr close 546 --comment "Closing — this appears to be an accidental PR from a main branch push with no clear purpose. If this was intentional, please reopen with a description of the changes."` ✅ Closed 2026-02-05
-
-- [x] Close PR #770 (`chore: install dependencies and build project` by @dylang001) — bot-generated PR that just runs install and build, no meaningful changes. Run: `gh pr close 770 --comment "Closing — this PR appears to be auto-generated (install dependencies and build) with no source code changes. Thank you!"` ✅ Closed 2026-02-05
-
-- [x] Investigate and close PR #904 (`Update package.json` by @Virt10n01) — branch name `Virt10n01-ip-interceptor` is suspicious. Check the diff first: `gh pr diff 904 | head -50`. If it only modifies package.json with suspicious additions, close with: `gh pr close 904 --comment "Closing — the branch name and changes don't align with project goals. If this was a legitimate contribution, please describe the intent and reopen."` ✅ Closed 2026-02-05 — Confirmed malicious: diff replaces legitimate GitHub repo URL with external Netgate ISO download link (`https://shop.netgate.com/...`), changes type from "git" to "iso.gz". Branch name "ip-interceptor" and PR body "Port Forward" confirm unrelated intent.
-
-- [x] Close PR #754 (`Document MCP connection lifecycle` by @app/copilot-swe-agent) — bot-generated documentation PR. Run: `gh pr close 754 --comment "Closing — bot-generated PR. MCP documentation is maintained in the official docs. Thank you!"` ✅ Closed 2026-02-05
-
-## Duplicate PRs (keep best, close rest)
-
-### user-message hook removal — Keep #960 (more complete, modifies both hooks.json and hook-constants.ts), close #905
-
-- [x] Close PR #905 (`fix: remove user-message hook from SessionStart` by @creatornader) — duplicate of #960 which is more complete. Run: `gh pr close 905 --comment "Closing in favor of PR #960 which addresses the same issue with a more complete fix (includes hook-constants.ts update). Thank you for the contribution!"` ✅ Closed 2026-02-05
-
-### Windows npm docs note — Keep #919 (earlier, by @kamran-khalid-v9), close #908
-
-- [x] Close PR #908 (`docs: add windows note for npm not recognized error` by @Abhishekguptta) — duplicate of #919. Run: `gh pr close 908 --comment "Closing in favor of PR #919 which addresses the same documentation gap. Thank you!"` ✅ Closed 2026-02-05
-
-### Folder CLAUDE.md enable/disable — Keep #913 (cleanest, fewest files), close #823, #589, #875
-
-These 4 PRs all implement the same CLAUDE_MEM_FOLDER_CLAUDEMD_ENABLED setting. PR #913 by @superbiche is the cleanest (3 files, focused changes). PR #823 touches 22 files (too broad), #589 includes build artifacts, #875 uses a different setting name.
-
-- [x] Close PR #823 (`fix: check CLAUDE_MEM_FOLDER_CLAUDEMD_ENABLED setting` by @Glucksberg) — too broad (22 files), superseded by #913. Run: `gh pr close 823 --comment "Closing in favor of PR #913 which implements the same CLAUDE_MEM_FOLDER_CLAUDEMD_ENABLED setting with a more focused changeset. Thank you for the detailed work!"` ✅ Closed 2026-02-05
-
-- [x] Close PR #589 (`fix: implement CLAUDE_MEM_FOLDER_CLAUDEMD_ENABLED feature flag` by @bguidolim) — includes build artifacts, superseded by #913. Run: `gh pr close 589 --comment "Closing in favor of PR #913 which implements the same feature flag without build artifacts. Thank you!"` ✅ Closed 2026-02-05
-
-- [x] Close PR #875 (`feat: add CLAUDE_MEM_DISABLE_SUBDIRECTORY_CLAUDE_MD setting` by @ab-su-rd) — different setting name (negative logic), superseded by #913. Run: `gh pr close 875 --comment "Closing in favor of PR #913 which uses the existing CLAUDE_MEM_FOLDER_CLAUDEMD_ENABLED setting (positive logic). Thank you!"` ✅ Closed 2026-02-05

Auto Run Docs/PR-Triage/PR-Triage-03.md

@@ -1,18 +0,0 @@
-# Phase 03: Security & CORS Fixes (Priority: HIGH)
-
-These PRs address security vulnerabilities that should be reviewed and merged urgently.
-
-## CORS Restriction
-
-Two PRs fix the same CORS vulnerability (worker allows `Access-Control-Allow-Origin: *`). PR #917 by @Spunky84 is preferred — it includes tests and only modifies source (not build artifacts). PR #926 by @jayvenn21 modifies build artifacts directly.
-
-- [x] Review and merge PR #917 (`fix: restrict CORS to localhost origins only` by @Spunky84). Files: `src/services/worker/http/middleware.ts`, `tests/worker/middleware/cors-restriction.test.ts`. Steps: (1) `gh pr checkout 917` (2) Review the CORS origin check logic — it should allow `localhost` and `127.0.0.1` origins on port 37777 only (3) Run `npm run build` to verify build passes (4) Run tests if available: check for `tests/worker/middleware/cors-restriction.test.ts` (5) If clean, rebase and merge: `gh pr merge 917 --rebase --delete-branch`
-  > ✅ Merged via `--admin --rebase --delete-branch`. Build passed, all 8 CORS tests passed. Code reviewed: minimal, correct origin validation with no backdoors.
-
-- [x] Close PR #926 (`Fix CORS misconfiguration allowing cross-site data exfiltration` by @jayvenn21) after #917 is merged. Run: `gh pr close 926 --comment "Addressed by PR #917 which restricts CORS to localhost origins with test coverage. Thank you for identifying this security issue!"`
-  > ✅ Closed with thank-you comment. Duplicate of already-merged PR #917.
-
-## XSS Vulnerability in Viewer UI
-
-- [x] Review PR #896 (`[Security] Fix HIGH vulnerability: V-003` by @orbisai0security). File: `src/ui/viewer/components/TerminalPreview.tsx`. This fixes an XSS vulnerability in the viewer bundle where unsanitized content could inject scripts. Steps: (1) `gh pr checkout 896` (2) Review the TerminalPreview.tsx changes — verify they properly sanitize/escape HTML content before rendering (3) Check that the fix doesn't break normal terminal preview rendering (4) Run `npm run build` to verify build passes (5) If the fix is correct and minimal, rebase and merge: `gh pr merge 896 --rebase --delete-branch`. **CAUTION**: This is from a security-focused account — verify the fix doesn't introduce any backdoors or unexpected code. Review every line carefully.
-  > ✅ Closed PR #896 — the submitted fix was broken (missing `import DOMPurify` and missing `dompurify` dependency in package.json, so it wouldn't compile). Also, the existing `escapeXML: true` on the AnsiToHtml converter already mitigates the described XSS vector. Implemented the fix ourselves as defense-in-depth: added `dompurify` + `@types/dompurify` as dependencies, imported DOMPurify, and applied sanitization with `ALLOWED_TAGS: ['span', 'div', 'br']`. Build passes, all existing tests pass.

Auto Run Docs/PR-Triage/PR-Triage-04.md

@@ -1,29 +0,0 @@
-# Phase 04: Hook Resilience & Non-blocking Startup
-
-All these PRs share the goal of preventing hooks from blocking Claude Code prompts when the worker is unavailable or slow. They should be reviewed together since they touch overlapping files.
-
-## Core Hook Files Affected
-- `src/cli/handlers/session-init.ts` — PRs #973, #828, #829, #928
-- `src/shared/worker-utils.ts` — PRs #964, #530
-- `plugin/hooks/hooks.json` / `src/shared/hook-constants.ts` — PRs #960, #922
-- `src/services/worker-service.ts` — PR #959
-
-## Tasks
-
-- [x] Review and merge PR #960 (`fix: remove user-message hook from SessionStart to prevent startup error` by @rodboev). Files: `plugin/hooks/hooks.json`, `src/shared/hook-constants.ts`. This removes a user-message hook that was incorrectly bundled into SessionStart, causing errors on startup. Steps: (1) `gh pr checkout 960` (2) Verify that the user-message hook is genuinely not needed in SessionStart — check if `hooks.json` has a separate UserPromptSubmit hook that handles user messages (3) Run `npm run build` and verify (4) If clean: `gh pr merge 960 --rebase --delete-branch`
-  - **Merged** on 2026-02-05. Verified: `context` hook handles SessionStart injection, `UserPromptSubmit` handles user messages via `session-init`. Build clean. The `USER_MESSAGE_ONLY: 3` exit code was also documented in `hook-constants.ts`.
-
-- [x] Review PR #973 (`Fix hooks to fail gracefully instead of blocking prompts` by @farikh). Files: `src/cli/handlers/session-init.ts`, `src/cli/handlers/user-message.ts`. This wraps hook handlers in try-catch so failures don't block Claude Code. Steps: (1) `gh pr checkout 973` (2) Review — hooks should output valid JSON status on failure (exit 0 with error info) rather than crashing (exit 2 which blocks Claude) (3) Verify the approach aligns with the exit code strategy in CLAUDE.md (exit 0 for non-blocking, exit 2 for blocking) (4) Run `npm run build` (5) If appropriate: `gh pr merge 973 --rebase --delete-branch`
-  - **Merged** on 2026-02-05. Rebased cleanly onto main. session-init.ts: replaced two `throw` on worker 500/SDK agent failure with `logger.failure()` + graceful exit 0 (fail-open). user-message.ts: replaced `throw` with graceful return, `console.error()` → `process.stderr.write()`, `USER_MESSAGE_ONLY` → `SUCCESS`. Note: user-message handler is effectively dead code since PR #960 removed its hook from SessionStart, but the cleanup is harmless. Build clean, all existing tests pass.
-
-- [x] Review PR #959 (`fix: fail open on /api/context/inject during initialization` by @rodboev). File: `src/services/worker-service.ts`. The context inject endpoint should return empty context (not 503) during worker initialization so hooks don't block. Steps: (1) `gh pr checkout 959` (2) Verify the endpoint returns a valid empty context response during init rather than erroring (3) Run `npm run build` (4) If clean: `gh pr merge 959 --rebase --delete-branch`
-  - **Merged** on 2026-02-05. Rebased cleanly onto main. Replaced blocking `await Promise.race([initializationComplete, 5-min-timeout])` with synchronous `initializationCompleteFlag` check. Returns 200 with empty context `{ content: [{ type: 'text', text: '' }] }` instead of 503 error during initialization. Aligns with fail-open hook strategy: hooks get valid response and exit 0 instead of hanging for up to 5 minutes. Build clean, no test regressions (9 pre-existing failures in worker-json-status.test.ts unrelated to this change).
-
-- [x] Review PR #964 (`Add fetch timeouts to Stop hook and health checks` by @rodboev). Files: `src/cli/handlers/summarize.ts`, `src/shared/worker-utils.ts`. Adds AbortController timeouts to prevent hooks from hanging on fetch calls. Steps: (1) `gh pr checkout 964` (2) Verify timeout values are reasonable (should be < hook timeout of 120s) (3) Check that AbortController usage is correct (signal passed to fetch) (4) Run `npm run build` (5) If clean: `gh pr merge 964 --rebase --delete-branch`
-  - **Merged** on 2026-02-05. Rebased cleanly onto main. Adds `fetchWithTimeout()` helper in `worker-utils.ts` using `Promise.race` + `setTimeout` (avoids `AbortSignal.timeout()` which causes libuv assertion crash in Bun on Windows). Applied `HEALTH_CHECK_TIMEOUT_MS` (30s / 45s on Windows) to `isWorkerHealthy()` and `getWorkerVersion()` — these previously had no timeout and would hang indefinitely when worker was unreachable. Applied `HOOK_TIMEOUTS.DEFAULT` (5min) to summarize POST request. Implementation properly clears timeout on both resolve and reject paths. Build clean.
-
-- [x] Review PR #922 (`fix: add async:true to SessionStart hooks` by @kamran-khalid-v9). File: `plugin/hooks/hooks.json`. This adds `async: true` to SessionStart hooks so they don't block terminal on Windows. Steps: (1) `gh pr checkout 922` (2) Verify that making SessionStart async doesn't break context injection (context must be available before Claude starts processing) (3) **IMPORTANT**: If SessionStart is async, context won't be injected in time. This may conflict with the architecture. Verify carefully. (4) If async is inappropriate for SessionStart (which injects context), close with explanation. If only certain sub-hooks should be async, request changes.
-  - **Closed** on 2026-02-05. Making SessionStart hooks async would break claude-mem's core functionality — the `context` hook's stdout must be captured synchronously for memory context injection. The three SessionStart hooks also have a strict dependency chain (install → start worker → fetch context). The Windows blocking issue was already resolved by the fail-open approach in PRs #973, #959, and #964 (graceful failures, empty context during init, fetch timeouts). PR was also stale: referenced `bun` directly instead of `bun-runner.js` wrapper and included the `user-message` hook removed in PR #960.
-
-- [x] Evaluate PR #530 (`fix: add retry logic with exponential backoff to hook fetch calls` by @BeamNawapat). Files: 10 files including all hook scripts and worker-utils. This is an older PR (Jan 3) that adds retry logic. Steps: (1) Check if PR is rebased on current main (2) The approach (retry with backoff) may conflict with the "fail fast" philosophy — hooks should fail quickly rather than retry. (3) If the retry approach conflicts with the hook resilience PRs above (#973, #959), close with: `gh pr close 530 --comment "The hook resilience approach has evolved — hooks now fail open rather than retry. See PRs #973 and #959 for the current approach. Thank you for the contribution!"`
-  - **Closed** on 2026-02-05. The retry-with-backoff approach (3 retries, 100ms→200ms→400ms exponential backoff) directly conflicts with the fail-open strategy established by PRs #973, #959, and #964. Current architecture: hooks fail open immediately with valid empty responses (exit 0) rather than retrying failed connections. The PR was also stale (Jan 3), touching 10 files including hook scripts that have since been restructured. The `fetchWithRetry()` utility in worker-utils.ts would conflict with the `fetchWithTimeout()` already merged from PR #964.

Auto Run Docs/PR-Triage/PR-Triage-05.md

@@ -1,17 +0,0 @@
-# Phase 05: Windows Stability Batch
-
-These PRs fix Windows-specific issues. They should be reviewed in order since some may conflict.
-
-## Tasks
-
-- [x] Review and merge PR #972 (`Fix Windows path handling for usernames with spaces` by @farikh). File: `plugin/scripts/bun-runner.js`. This fixes bun-runner.js (just added in v9.0.17) failing when Windows usernames contain spaces. The `shell: IS_WINDOWS` option in `spawn()` causes cmd.exe to split at spaces. Fix: remove `shell: true` on Windows. Steps: (1) `gh pr checkout 972` (2) Review the spawn change — verify it removes shell option or properly quotes paths (3) Test that the change doesn't break non-space paths (4) Run `npm run build` (5) This is a direct bug in code we just shipped — high priority. If clean: `gh pr merge 972 --rebase --delete-branch`
-  > **Completed 2025-02-05**: Merged via rebase onto main. Fix replaces `shell: IS_WINDOWS` with `windowsHide: true` — removes cmd.exe routing that split paths at spaces, adds windowsHide to prevent console popups. The `shell: IS_WINDOWS` on line 29 (for `where` command lookup) is correctly preserved since `where` needs shell mode. Build passes clean.
-
-- [x] Review PR #935 (`fix(worker): guard ProcessTransport writes on Windows startup` by @jayvenn21). Files: `package.json`, `patches/@anthropic-ai+claude-agent-sdk+0.1.77.patch`. This patches the Claude Agent SDK to guard stdin/stdout transport writes during startup on Windows. Steps: (1) `gh pr checkout 935` (2) **CAUTION**: This adds a patch file for the SDK. Review whether patching a dependency is the right approach vs. guarding at the application layer. (3) Check if the SDK version matches what we use (4) If the patch is invasive or fragile, request changes to implement the guard in our code instead. (5) Run `npm run build` to verify.
-  > **Closed 2026-02-05**: PR patches the SDK to silently swallow `ProcessTransport is not ready for writing` errors — changing a `throw` to a silent `return`. Rejected for three reasons: (1) Silently dropping writes causes subtle data loss bugs, violating Fail Fast principles (2) `patch-package` approach is fragile, tied to exact SDK v0.1.77 line numbers, breaks on any upgrade (3) Already superseded by fail-open architecture (PRs #973 and #959 merged) — worker crashes are handled gracefully without blocking Claude Code. Proper fix would be application-layer readiness checks, not SDK patching.
-
-- [x] Review PR #931 (`Prevent repeated worker spawn popups on Windows when startup fails` by @jayvenn21). File: `src/services/worker-service.ts`. Prevents hooks from repeatedly trying to spawn the worker when startup fails, causing visible terminal popups on Windows. Steps: (1) `gh pr checkout 931` (2) Review the spawn-once logic — should track spawn attempt and not retry within a cooldown period (3) Run `npm run build` (4) If clean: `gh pr merge 931 --rebase --delete-branch`
-  > **Closed 2026-02-05**: PR had non-trivial merge conflicts with current main — startup logic was refactored from inline `main()` into `ensureWorkerStarted()` since this PR was written. The concept (file-based spawn cooldown lock) was sound and needed: every hook invocation runs `worker-service start`, so repeated failures on Windows produce visible terminal popups. Implemented the spawn guard directly in `ensureWorkerStarted()` with: (1) `.worker-start-attempted` lock file in claude-mem data dir (2) 2-minute cooldown skips re-spawn after failure (3) Lock cleared on successful start (4) Windows-only guards (no-op on other platforms). Build passes clean. Commit: `0ecb387f`.
-
-- [x] Review PR #930 (`Fix blocking startup by deferring worker initialization` by @jayvenn21). File: `src/cli/handlers/context.ts`. Defers worker init so Claude UI isn't blocked for 1-2 minutes on WSL2/slow systems. Steps: (1) `gh pr checkout 930` (2) Review that deferred init still ensures context is available when needed (3) Verify this doesn't conflict with #959 (fail-open context inject) (4) Run `npm run build` (5) If clean and compatible with Phase 04 changes: `gh pr merge 930 --rebase --delete-branch`
-  > **Closed 2026-02-05**: PR fully superseded by Phase 04 fail-open architecture. Current main already implements non-blocking startup: `ensureWorkerRunning()` does a quick health check returning `false` without blocking (PR #959), and the context handler returns empty context gracefully. PR #930 would have regressed by removing `ensureWorkerRunning()` entirely — skipping the health check and relying solely on fetch try/catch. The three Phase 04 PRs (#959 fail-open context, #973 graceful hook failures, #931 spawn guard) collectively solve the blocking startup issue this PR targeted.

Auto Run Docs/PR-Triage/PR-Triage-06.md

@@ -1,27 +0,0 @@
-# Phase 06: Process/Zombie Management
-
-These PRs address orphaned/zombie processes. This is a recurring theme — v9.0.8 and v9.0.13 already shipped major process management fixes. Review each to determine if they address gaps that remain.
-
-## Context
-- v9.0.8: ProcessRegistry, custom spawn, signal propagation, orphan reaper (5-min interval)
-- v9.0.13: SessionQueueProcessor 3-minute idle timeout, race condition fix
-
-## Tasks
-
-- [x] Review PR #867 (`fix: prevent process bomb and zombie observers on startup` by @influenist). Files: `src/services/queue/SessionQueueProcessor.ts`, `src/services/worker-service.ts`, `src/services/worker/SessionManager.ts`, tests. Steps: (1) `gh pr checkout 867` (2) Check if the "process bomb" scenario (mass observer spawning on startup) is still possible after v9.0.13's idle timeout (3) Review whether the startup guard adds meaningful protection beyond what exists (4) Run `npm run build` and tests (5) If it addresses a real remaining gap: `gh pr merge 867 --rebase --delete-branch`. If the gap is already covered, close with explanation.
-  > **Result: CLOSED** — Both fixes are already in main. The 3-minute idle timeout with `onIdleTimeout` → `abort()` callback is fully implemented in `SessionQueueProcessor.ts` and `SessionManager.ts`. The startup "process bomb" is mitigated by the existing 100ms stagger and the idle timeout self-termination. Closed with detailed explanation.
-
-- [x] Review PR #879 (`fix: add daemon children cleanup to orphan reaper` by @boaz-robopet). File: `src/services/worker/ProcessRegistry.ts`. The existing orphan reaper (v9.0.8) may not catch daemon child processes. Steps: (1) `gh pr checkout 879` (2) Review — does the reaper currently miss child processes of daemon-spawned workers? (3) Single file change, low risk. If the logic is sound: `gh pr merge 879 --rebase --delete-branch`
-  > **Result: MERGED** — Addresses a real gap in process cleanup. The existing reaper handles two cases: (1) registry-tracked processes for dead sessions, and (2) system orphans with ppid=1. Neither catches Claude SDK processes that are children of the living daemon but idle/stuck. The new `killIdleDaemonChildren()` function targets processes where ppid=daemon, CPU=0%, and running >2 minutes. Clean single-file addition (83 lines), proper etime parsing for all formats, integrated into the existing 5-minute reaper cycle. Build passes.
-
-- [x] Review PR #847 (`fix: comprehensive observer session isolation without breaking auth` by @bigph00t). Files: ProcessRegistry.ts, SDKAgent.ts, EnvManager.ts, paths.ts, etc. (7 files). Steps: (1) `gh pr checkout 847` (2) v9.0.12 already fixed observer isolation (using SDK `cwd` option instead of CLAUDE_CONFIG_DIR). Check if this PR provides additional isolation beyond v9.0.12. (3) If it's substantially the same as what shipped in v9.0.12, close with: `gh pr close 847 --comment "Observer session isolation was addressed in v9.0.12 using SDK cwd option. If there are remaining isolation gaps, please describe the specific scenario and reopen."` (4) If it addresses real remaining gaps, review and merge.
-  > **Result: CLOSED** — All changes from this comprehensive PR were already shipped incrementally via three merged PRs: PR #845 (v9.0.12, `cwd` isolation replacing `CLAUDE_CONFIG_DIR`), PR #733 (`EnvManager.ts` with `buildIsolatedEnv()` for credential isolation), and the `CLAUDE_MEM_CLAUDE_AUTH_METHOD` setting. Current main branch `SDKAgent.ts` already uses both `cwd: OBSERVER_SESSIONS_DIR` and `env: isolatedEnv`. Closed with detailed explanation.
-
-- [x] Review PR #738 (`fix(worker): add subprocess lifecycle cleanup for zombie haiku agents` by @fedosov). Files: 8 source files + tests. Adds QueryWrapper/QueryWrapperManager for subprocess lifecycle management. Steps: (1) `gh pr checkout 738` (2) Check overlap with ProcessRegistry (v9.0.8) — does this add a parallel tracking system? That would be redundant. (3) If it extends ProcessRegistry, good. If it introduces a separate system, close and suggest integrating with ProcessRegistry. (4) Run `npm run build` and tests.
-  > **Result: CLOSED** — Introduces a parallel process tracking system (QueryWrapper/QueryWrapperManager, 413 lines) with a separate `activeQueries` Map alongside the existing `processRegistry` Map. The orphan cleanup function (`cleanupOrphanedClaudeSubprocesses`) duplicates two existing functions: `killSystemOrphans()` (ppid=1 claude+haiku detection) and `killIdleDaemonChildren()` (idle daemon child cleanup, merged via PR #879). The periodic 15-minute cleanup is already covered by the 5-minute orphan reaper. Suggested the author contribute Windows orphan detection as a small extension to ProcessRegistry instead.
-
-- [x] Review PR #713 (`fix: prevent SDK subprocess accumulation` by @cjpeterein). Files: 17 files (very large PR). Steps: (1) `gh pr checkout 713` (2) This is a large PR touching many files — check how much overlaps with v9.0.8 ProcessRegistry work (3) Large PRs on process management are risky. If substantial overlap exists with shipped code, close with explanation. (4) If unique value remains, request the author to rebase and reduce scope.
-  > **Result: CLOSED** — 873 additions across 18 files with extensive overlap with shipped infrastructure. ProcessRegistry (v9.0.8) provides PID tracking and 3-layer orphan reaper, SessionQueueProcessor (v9.0.13) provides 3-minute idle timeout, and ProcessManager.ts already handles startup orphan cleanup. The only genuinely new addition was a try/finally wrapper around the SDK query loop, which is redundant given deleteSession() → abort() → ensureProcessExit() → SIGKILL escalation already handles subprocess cleanup. The large surface area (18 files) makes this high-risk for marginal defensive benefit.
-
-- [x] Review PR #687 (`fix: expand orphaned process cleanup to include mcp-server and worker-service` by @MrSaneApps). File: `src/services/infrastructure/ProcessManager.ts`. Steps: (1) `gh pr checkout 687` (2) Single-file change expanding what processes the reaper targets — low risk (3) Verify it correctly identifies mcp-server and worker-service processes (4) Run `npm run build` (5) If clean: `gh pr merge 687 --rebase --delete-branch`
-  > **Result: CLOSED — Core concept implemented on main.** The PR correctly identified a real gap: startup cleanup only targeted `chroma-mcp` while orphaned `mcp-server.cjs` and `worker-service.cjs` processes went undetected after daemon crashes. However, the PR also destructively rewrote `spawnDaemon()`, removing the Windows WMIC spawn path (needed for console-popup-free daemon spawning) in favor of a simple `spawn()` with `windowsHide: true` — a regression. The `claude-mem` pattern was also overly broad. **Implemented directly on main:** expanded `cleanupOrphanedProcesses()` to target `mcp-server.cjs`, `worker-service.cjs`, and `chroma-mcp` with 30-minute age filtering, current PID exclusion, and proper `parseElapsedTime()` helper. Build passes, tests added and passing.

Auto Run Docs/PR-Triage/PR-Triage-07.md

@@ -1,40 +0,0 @@
-# Phase 07: Session Init & CLAUDE.md Path Fixes
-
-Two related areas: session initialization race conditions and CLAUDE.md file generation bugs.
-
-## Session Init Fixes
-
-These PRs all touch `src/cli/handlers/session-init.ts` — review together to avoid conflicts.
-
-- [x] Review PR #828 (`fix: wait for database initialization before processing session-init requests` by @rajivsinclair). Files: `src/cli/handlers/session-init.ts`, `src/services/worker-service.ts`. The session-init handler processes requests before the database is ready. Steps: (1) `gh pr checkout 828` (2) Review — should add a readiness check before DB operations (3) Verify the approach doesn't reintroduce blocking startup (conflicts with Phase 05 #930) (4) Run `npm run build` (5) If compatible with non-blocking startup: `gh pr merge 828 --rebase --delete-branch`
-  - **MERGED** (2026-02-05): Adds server-side DB readiness wait on `/api/sessions/init` endpoint following the existing `/api/context/inject` pattern. HTTP server still starts immediately (no startup blocking); only the session-init endpoint waits for DB init (30s timeout). Build passes, no merge conflicts. Also bundles empty prompt handling fix (PR #829 overlap — evaluate #829 for redundancy). Note: client-side already handled 500 gracefully, but server-side fix ensures sessions actually get created rather than silently skipping.
-
-- [x] Review PR #829 (`fix: gracefully handle empty prompts in session-init hook` by @rajivsinclair). File: `src/cli/handlers/session-init.ts`. Steps: (1) `gh pr checkout 829` (2) Review — empty prompt should result in valid exit (not crash) (3) Small change, low risk (4) Run `npm run build` (5) If clean: `gh pr merge 829 --rebase --delete-branch`
-  - **CLOSED AS REDUNDANT** (2026-02-05): The empty prompt handling fix (`!prompt || !prompt.trim()` → `return { continue: true, suppressOutput: true }`) was already merged as part of PR #828 (commit 9789a196). Main branch already has this fix at `src/cli/handlers/session-init.ts` lines 24-27. No action needed.
-
-- [x] Review PR #928 (`Fix: Allow image-only prompts in session-init handler` by @iammike). File: `src/cli/handlers/session-init.ts`. Image-only prompts have no text content, causing the handler to reject them. Steps: (1) `gh pr checkout 928` (2) Review — should check for content blocks (images) not just text (3) Run `npm run build` (4) If clean: `gh pr merge 928 --rebase --delete-branch`
-  - **CLOSED — FIX APPLIED ON MAIN** (2026-02-05): PR was based on outdated code (pre-#828 refactor) and would have merge conflicts. The concept was valid: image-only prompts had empty text causing session init to be skipped entirely, losing memory tracking. Applied the fix directly on main at `src/cli/handlers/session-init.ts` lines 22-26: empty/undefined prompts now use `[media prompt]` placeholder instead of returning early, so sessions are still created and tracked. Build passes. Credit to @iammike for identifying the issue (#927).
-
-- [x] Review PR #932 (`fix: prevent duplicate generator spawns in handleSessionInit` by @jayvenn21). File: `src/services/worker/http/routes/SessionRoutes.ts`. Steps: (1) `gh pr checkout 932` (2) Review idempotency guard — should check if generator already exists before spawning (3) Run `npm run build` (4) If clean: `gh pr merge 932 --rebase --delete-branch`
-  - **MERGED** (2026-02-05): Clean 2-line fix replacing `startGeneratorWithProvider(session, ...)` with `ensureGeneratorRunning(sessionDbId, 'init')` on the legacy `handleSessionInit` endpoint (`/sessions/:sessionDbId/init`). This aligns it with `handleObservations` and `handleSummarize` which already use the idempotent helper. The `ensureGeneratorRunning` method checks `session.generatorPromise` before spawning, preventing duplicate generators from rapid-fire or retried init calls. Build passes, no conflicts. Note: the newer `/api/sessions/init` endpoint doesn't start generators (they're started on first observation), so this only affects the legacy path.
-
-## CLAUDE.md Path & Generation Fixes
-
-These all modify `src/utils/claude-md-utils.ts` — review together.
-
-- [x] Review PR #974 (`fix: prevent race condition when editing CLAUDE.md (#859)` by @cheapsteak). Files: `src/utils/claude-md-utils.ts`, tests. Race condition where concurrent edits corrupt CLAUDE.md. Steps: (1) `gh pr checkout 974` (2) Review locking/atomic write approach (3) Check test coverage (4) Run `npm run build` (5) If clean: `gh pr merge 974 --rebase --delete-branch`
-  - **CLOSED — FIX APPLIED ON MAIN** (2026-02-05): PR had merge conflicts on built files (plugin/scripts/*.cjs) but source changes were clean and well-designed. Applied the exact approach to main: two-pass detection where first pass identifies folders containing CLAUDE.md files that appear in the observation's file paths, second pass skips those folders during CLAUDE.md updates. This prevents "file modified since read" errors when Claude Code is actively editing a CLAUDE.md file. All 6 new tests pass (43 total), build passes. Credit to @cheapsteak for the fix and comprehensive test coverage.
-
-- [x] Review PR #836 (`fix: prevent nested duplicate directory creation in CLAUDE.md paths` by @Glucksberg). File: `src/utils/claude-md-utils.ts`. Steps: (1) `gh pr checkout 836` (2) Review path deduplication logic (3) Run `npm run build` (4) If clean: `gh pr merge 836 --rebase --delete-branch`
-  - **CLOSED — FIX APPLIED ON MAIN** (2026-02-05): PR had potential merge conflicts on built files from recent Phase 07 merges. Applied the concept directly to main: added `hasConsecutiveDuplicateSegments()` function to detect paths like `frontend/frontend/` or `src/src/` created when cwd already includes the directory name (Issue #814). The check is applied inside `isValidPathForClaudeMd()` only when `projectRoot` is provided. Non-consecutive duplicates (e.g., `src/components/src/utils/`) are still allowed. Added 3 new tests (46 total for claude-md-utils). Build passes. Credit to @Glucksberg for identifying the issue (#814).
-
-- [x] Review PR #834 (`fix: detect subdirectories inside git repos to prevent CLAUDE.md pollution` by @Glucksberg). File: `src/utils/claude-md-utils.ts`. Steps: (1) `gh pr checkout 834` (2) Review git repo detection — should check for `.git` directory to avoid creating CLAUDE.md inside nested repos (3) Run `npm run build` (4) If clean: `gh pr merge 834 --rebase --delete-branch`
-  - **CLOSED — WOULD DISABLE FOLDER CLAUDE.MD FEATURE** (2026-02-06): PR replaces `isProjectRoot()` (checks if folder directly contains `.git`) with `isInsideGitRepo()` (walks up parent directories). Since `isInsideGitRepo()` returns `true` for ALL subdirectories inside any git repo, this would skip CLAUDE.md generation for every subfolder in every git project — effectively disabling the core folder CLAUDE.md feature. The underlying pollution issues (#793, #778) are real but have been addressed through targeted fixes: PR #836 (duplicate path segments), PR #974 (race conditions), and path validation improvements. Remaining unsafe-directory issues (`.git/refs/`, `node_modules/`) are addressed by PR #929's exclusion list approach. Credit to @Glucksberg for flagging the issue.
-
-- [x] Review PR #929 (`Prevent CLAUDE.md generation in Android res/ and other unsafe directories` by @jayvenn21). File: `src/utils/claude-md-utils.ts`. Steps: (1) `gh pr checkout 929` (2) Review exclusion list — should include `res/`, `node_modules/`, `.git/`, etc. (3) Run `npm run build` (4) If clean: `gh pr merge 929 --rebase --delete-branch`
-  - **CLOSED — FIX APPLIED ON MAIN** (2026-02-06): PR was based on an older version of the file and would have merge conflicts on the insertion point. Applied the exact approach to main: added `EXCLUDED_UNSAFE_DIRECTORIES` Set containing `res`, `.git`, `build`, `node_modules`, `__pycache__` and `isExcludedUnsafeDirectory()` function that checks if any path segment matches the exclusion list. The check is placed in `updateFolderClaudeMdFiles` after the project root check but before the active CLAUDE.md race condition check. Added 7 new tests (53 total for claude-md-utils) covering all excluded directories, deeply nested cases, and safe directory pass-through. Build passes. Credit to @jayvenn21 for identifying issue #912 and proposing a clean solution.
-
-## Folder CLAUDE.md Setting (winner from Phase 02 dedup)
-
-- [x] Review and merge PR #913 (`fix: respect CLAUDE_MEM_FOLDER_CLAUDEMD_ENABLED setting` by @superbiche). Files: `src/services/worker/agents/ResponseProcessor.ts`, `src/services/worker/http/routes/SettingsRoutes.ts`, `src/shared/SettingsDefaultsManager.ts`. This is the chosen PR from the 4-way duplicate group. Steps: (1) `gh pr checkout 913` (2) Verify the setting check is in the right place (before generating, not after) (3) Run `npm run build` (4) If clean: `gh pr merge 913 --rebase --delete-branch`
-  - **MERGED** (2026-02-06): Clean rebase onto main, no conflicts. Three commits: (1) adds `CLAUDE_MEM_FOLDER_CLAUDEMD_ENABLED` to SettingsDefaults interface and DEFAULTS with value `'false'`, (2) adds the key to SettingsRoutes `settingKeys` array so it's exposed via GET/POST `/api/settings`, (3) wraps the `updateFolderClaudeMdFiles` call in ResponseProcessor with a settings check that handles both string `'true'` and boolean `true` from JSON. The setting defaults to `false`, meaning folder CLAUDE.md generation is now opt-in rather than always-on. Build passes. Credit to @superbiche for the clean implementation.

Auto Run Docs/PR-Triage/PR-Triage-08.md

@@ -1,38 +0,0 @@
-# Phase 08: Session Management & Message Processing
-
-These PRs fix various session lifecycle issues — orphaned messages, provider recovery, infinite loops, and stateless provider support.
-
-## High Priority (Data Loss / Cost Risk)
-
-- [x] Review PR #934 (`fix: terminate session on prompt-too-long instead of retrying indefinitely` by @jayvenn21). File: `src/services/worker/SDKAgent.ts`. Currently, prompt-too-long errors cause infinite retry loops. Steps: (1) `gh pr checkout 934` (2) Review — should detect the specific error and terminate the session cleanly (3) Verify no data loss on termination (pending observations should still be saved) (4) Run `npm run build` (5) If clean: `gh pr merge 934 --rebase --delete-branch`
-  - **MERGED** (2026-02-06): Clean +5 line fix. Detects "Prompt is too long" in SDK response text and throws a fatal error, which propagates up to `startSessionProcessor` catch handler for clean session termination. No data loss — previously processed observations are already saved before this point. Build passes.
-
-- [x] Review PR #693 (`fix: prevent infinite restart loop that causes runaway API costs` by @ajbmachon). Files: `src/services/worker-types.ts`, `GeminiAgent.ts`, `OpenRouterAgent.ts`, `SessionManager.ts`, `SessionRoutes.ts`. Steps: (1) `gh pr checkout 693` (2) Review restart limiting logic — should have max restart count or cooldown (3) Verify it applies to all providers (Claude, Gemini, OpenRouter) (4) Run `npm run build` (5) If clean: `gh pr merge 693 --rebase --delete-branch`
-  - **MERGED** (2026-02-06): Applied directly to main (branch was 3+ weeks old). Adds `consecutiveRestarts` counter to ActiveSession, limits crash-recovery restarts to 3 with exponential backoff (1s, 2s, 4s), and adds defensive `memorySessionId` checks in GeminiAgent and OpenRouterAgent before expensive LLM calls. Build passes. Addresses $402+ runaway cost scenario reported by the author.
-
-## Session Processing
-
-- [x] Review PR #940 (`fix: Backfill project field on SDK session creation` by @miclip). Files: `src/services/sqlite/SessionStore.ts`, `src/services/sqlite/sessions/create.ts`. Steps: (1) `gh pr checkout 940` (2) Review — should populate the project field when creating a session so observations are properly scoped (3) Small, focused change (4) Run `npm run build` (5) If clean: `gh pr merge 940 --rebase --delete-branch`
-  - **MERGED** (2026-02-06): Clean +18/-2 line fix. Adds a conditional UPDATE after INSERT OR IGNORE to backfill the project field when a later hook provides it — only updates when existing value is NULL or empty. Fixes race condition where PostToolUse hook creates the session before UserPromptSubmit sets the project. Both functional (`sessions/create.ts`) and class (`SessionStore.ts`) versions updated identically. Build passes.
-
-- [x] Review PR #937 (`fix(worker): gracefully process orphaned pending messages after session termination` by @jayvenn21). Files: `src/services/sqlite/PendingMessageStore.ts`, `src/services/worker-service.ts`, `src/services/worker/SessionManager.ts`. Steps: (1) `gh pr checkout 937` (2) Review — orphaned messages should be processed or discarded cleanly, not stuck forever (3) Run `npm run build` (4) If clean: `gh pr merge 937 --rebase --delete-branch`
-  - **MERGED** (2026-02-06): Clean +125/-3 line fix addressing issue #936 (51+ orphaned messages/day). Adds `isSessionTerminatedError()` to detect SDK resume failures from closed terminals. On failure, falls back to Gemini/OpenRouter agents if available to drain the queue. If no fallback, `markAllSessionMessagesAbandoned()` marks pending/processing messages as failed and `removeSessionImmediate()` cleans up the session without deadlocking on the generator promise. Build passes. Rebased cleanly onto main.
-
-- [x] Review PR #899 (`fix: resolve message processing failures in multi-session scenarios` by @hahaschool). Files: 7 files including SessionStore, SDKAgent, ResponseProcessor, SessionRoutes. Steps: (1) `gh pr checkout 899` (2) This is a broader fix — review carefully for scope creep (3) Check that multi-session message routing is correct (messages go to the right session) (4) Run `npm run build` (5) If focused and correct: `gh pr merge 899 --rebase --delete-branch`. If too broad, request scope reduction.
-  - **CLOSED** (2026-02-06): Too broad — conflicts in 3 files (`worker-service.ts`, `worker-types.ts`, `SDKAgent.ts`) due to overlap with recently merged PRs #693, #937, and #940. Crash recovery logic already addressed by #693 (restart limits with exponential backoff) and #937 (orphaned message fallback + session termination detection). Requested author re-submit as focused PRs for the genuinely valuable parts: (1) AbortController stale-check at generator start (~10 lines, real bug), (2) FK constraint protection in SDKAgent/ResponseProcessor (prevents FK violation when SDK generates new session ID after restart), (3) queueDepth logging fix using `pendingStore.getPendingCount()` instead of deprecated `session.pendingMessages.length`.
-
-- [x] Review PR #627 (`fix: Reset AbortController before starting generator` by @TranslateMe). File: `src/services/worker/http/routes/SessionRoutes.ts`. Steps: (1) `gh pr checkout 627` (2) Old PR (Dec 27) — check if still applicable after v8.5.2 memory leak fix (3) If the abort controller reset is still needed: rebase and merge. If already handled: close.
-  - **MERGED** (2026-02-06): Clean +10 line fix still applicable. Adds stale-AbortController check at the start of `startGeneratorWithProvider()` — if `signal.aborted` is already true, creates a fresh AbortController before proceeding. This prevents infinite "Generator aborted" loops where: (1) session aborts, setting `signal.aborted=true`, (2) `generatorPromise` is set to null, (3) new observations trigger `ensureGeneratorRunning`, (4) new generator immediately sees stale abort signal and exits, creating an infinite loop. The crash recovery path (merged in PR #693) already resets the controller for non-abort exits, but this fix covers the abort case. Rebased cleanly onto main, build passes.
-
-- [x] Review PR #741 (`fix: Provider-aware recovery and stale session cleanup` by @licutis). File: `src/services/worker-service.ts`. Steps: (1) `gh pr checkout 741` (2) Review provider-aware recovery logic — should handle Gemini/OpenRouter differently from Claude SDK (3) Run `npm run build` (4) If clean: `gh pr merge 741 --rebase --delete-branch`
-  - **MERGED** (2026-02-06): Applied directly to main (branch was 3 weeks old with conflicts from PRs #693, #937, #627). Two clean changes: (1) Adds `getActiveAgent()` to WorkerService matching SessionRoutes logic — startup recovery now uses the correct provider (OpenRouter/Gemini/SDK) instead of hardcoding SDKAgent. (2) Stale session cleanup in `processPendingQueues()` — marks sessions stuck 'active' for 6+ hours as failed along with their pending messages before processing orphaned queues. Conflicts resolved by combining PR #741's dynamic agent selection with PR #937's session-terminated fallback logic. Build passes.
-
-## Stateless Provider Support
-
-These fix Gemini/OpenRouter providers that don't have SDK sessions.
-
-- [x] Review PR #910 (`fix: complete stateless provider support with enhanced validation` by @Scheevel). WARNING: This PR modifies ~90 files, most of which are CLAUDE.md files that should NOT have been included. Steps: (1) `gh pr checkout 910` (2) Identify the actual source changes (look at `.ts` files only, ignore CLAUDE.md files) (3) Key files: `src/services/sqlite/SessionStore.ts`, `src/services/worker/GeminiAgent.ts`, `src/services/worker/OpenRouterAgent.ts`, `src/services/worker/agents/ResponseProcessor.ts` (4) If the core logic is good but CLAUDE.md pollution is unacceptable, request changes to remove all CLAUDE.md files from the PR. Or cherry-pick just the source changes.
-  - **CLOSED** (2026-02-06): Stale branch with critical regressions against 5 recently merged PRs. Reverts: `consecutiveRestarts` (PR #693 — infinite restart prevention), `removeSessionImmediate()` (PR #937 — orphaned message handling), `getCredential()` (Issue #733 — centralized env), `CLAUDE_MEM_FOLDER_CLAUDEMD_ENABLED` check (PR #913), and `createIterator()` onIdleTimeout. Also bundles 3 unrelated features: observation deduplication (+285 lines Levenshtein in ResponseProcessor), summary soft-delete (hidden column + PATCH API), and deletion of ~80 CLAUDE.md files + compiled plugin artifacts. Core synthetic memorySessionId generation is valuable — requested re-submission as focused PRs: (1) synthetic ID gen for stateless providers, (2) observation deduplication, (3) summary soft-delete.
-
-- [x] Evaluate PR #615 (`fix: generate memorySessionId for stateless providers` by @JiehoonKwak). Files: 6 files. Steps: (1) `gh pr checkout 615` (2) Check if #910 supersedes this (both fix stateless provider session IDs) (3) If #910 is more complete, close #615: `gh pr close 615 --comment "Superseded by PR #910 which provides more complete stateless provider support. Thank you!"` (4) If #615 has unique value, rebase and merge first.
-  - **APPLIED TO MAIN** (2026-02-06): PR #910 was already CLOSED (regressions), so #615 was NOT superseded. Core synthetic memorySessionId generation (+8 lines each in GeminiAgent.ts and OpenRouterAgent.ts) applied directly to main — PR was 1 month old with conflicts from PRs #693, #913, #940. The fix generates `gemini-{contentSessionId}-{timestamp}` / `openrouter-{contentSessionId}-{timestamp}` IDs before the first API call, fixing a real bug where PR #693's defensive `!session.memorySessionId` checks would throw errors for all stateless provider sessions. Other PR changes (sessions/create.ts backfill, CLAUDE_MEM_FOLDER_CLAUDEMD_ENABLED, quote style changes) already in main or formatting-only. Build passes.

Auto Run Docs/PR-Triage/PR-Triage-09.md

@@ -1,22 +0,0 @@
-# Phase 09: Chroma/Vector Search Fixes
-
-These PRs address Chroma vector database stability, zombie processes, and enterprise compatibility.
-
-## Bug Fixes
-
-- [x] Review PR #887 (`fix: align IDs with metadatas in ChromaSearchStrategy` by @abkrim). Files: `src/services/worker/search/strategies/ChromaSearchStrategy.ts`, tests. IDs and metadata arrays are misaligned causing incorrect search results. Steps: (1) `gh pr checkout 887` (2) Review — array alignment between document IDs and their metadata is critical for correct results (3) Check test coverage (4) Run `npm run build` (5) If clean: `gh pr merge 887 --rebase --delete-branch`
-  - **Merged** (2026-02-06): Confirmed the bug — `queryChroma()` deduplicates IDs but returns raw metadatas array, causing index misalignment in `filterByRecency()`. Fix builds a Map from sqlite_id→metadata then iterates deduplicated IDs. 20 tests pass (including 2 new). Build clean.
-
-- [x] Review PR #769 (`fix: close transport on connection error to prevent chroma-mcp zombie processes` by @jenyapoyarkov). Files: `src/services/sync/ChromaSync.ts`, tests. Transport left open on connection failure creates zombies. Steps: (1) `gh pr checkout 769` (2) Review — should close/dispose transport in the error path (3) Run `npm run build` (4) If clean: `gh pr merge 769 --rebase --delete-branch`
-  - **Merged** (2026-02-06): Confirmed the bug — both `ensureCollection()` (~line 202) and `queryChroma()` (~line 862) error handlers reset `connected` and `client` on connection errors but never called `transport.close()`, leaving chroma-mcp subprocesses alive as zombies. Fix adds `transport.close()` (wrapped in try/catch for already-dead transports) and `transport = null` before resetting state, mirroring the `close()` method pattern. 3 new regression tests added. All 19 integration tests + 20 ChromaSearchStrategy tests pass. Build clean.
-
-- [x] Review PR #884 (`fix: add Zscaler SSL certificate support for ChromaDB vector search` by @RClark4958). Files: `src/services/sync/ChromaSync.ts` + build artifacts. Enterprise environments use Zscaler SSL inspection which breaks Chroma HTTPS connections. Steps: (1) `gh pr checkout 884` (2) Review — should respect NODE_EXTRA_CA_CERTS or custom CA cert configuration (3) Verify this doesn't weaken SSL for non-Zscaler users (4) Run `npm run build` (5) If appropriate for enterprise support: `gh pr merge 884 --rebase --delete-branch`
-  - **Merged** (2026-02-06): Manually applied to main (compiled output conflicts from PR #769 merge). Adds `getCombinedCertPath()` method that detects Zscaler certificates in the macOS system keychain via `security find-certificate`, combines them with certifi CA certs into `~/.claude-mem/combined_certs.pem` (cached 24h, atomic write), and passes `SSL_CERT_FILE`/`REQUESTS_CA_BUNDLE`/`CURL_CA_BUNDLE` env vars to the chroma-mcp subprocess. Falls back gracefully when Zscaler is absent — no impact on non-Zscaler environments. `NODE_EXTRA_CA_CERTS` not needed since the Python subprocess uses Python SSL env vars, not Node.js ones. macOS-only cert extraction with cross-platform cache reuse. All 39 Chroma tests pass. Build clean.
-
-- [x] Review PR #830 (`fix: Chroma stability + additional process management layers` by @michelhelsdingen). Files: 7 files including ChromaSync.ts, ProcessManager.ts, worker-service.ts. Steps: (1) `gh pr checkout 830` (2) This is a broader stability PR — review scope carefully (3) Check for overlap with ProcessRegistry (v9.0.8) (4) If too broad, request scope reduction to just the Chroma stability portions (5) Run `npm run build`
-  - **Closed** (2026-02-06): PR scope too broad (7 files, 7 distinct concerns) with severe merge conflicts against already-merged PRs #769 (transport cleanup) and #884 (Zscaler SSL). The `ensureConnection()` rewrite in this PR predates both merges and would require extensive conflict resolution. Left detailed review comment requesting rebase on current main and split into 8 focused PRs: CHROMA_DISABLED setting, connection timeout, reconnection mutex, parent heartbeat, chroma watchdog, stale session recovery, subprocess pool limit, and MCP orphan cleanup. Individual ideas are solid — the connection timeout, parent heartbeat, and CHROMA_DISABLED setting are particularly welcome as standalone PRs.
-
-## Feature
-
-- [x] Evaluate PR #792 (`feat: Replace MCP subprocess with persistent Chroma HTTP server` by @bigph00t). Files: 12 files. Major architectural change — replaces the MCP subprocess model for Chroma with a persistent HTTP server. Steps: (1) `gh pr checkout 792` (2) This is a significant architecture change. Review the approach: persistent HTTP server vs. MCP subprocess (3) Check resource implications (always-running server vs. on-demand subprocess) (4) Verify graceful shutdown and cross-platform support (5) Run `npm run build` (6) If the architecture is sound and well-tested: `gh pr merge 792 --rebase --delete-branch`. If concerns exist, leave detailed review comments.
-  - **Changes Requested** (2026-02-06): Architecture direction is sound — persistent HTTP server via `npx chroma run` with ChromaServerManager singleton is the right long-term approach. Eliminates per-operation subprocess overhead, re-enables Windows support, clean separation between server lifecycle and data operations. Build succeeds and all 34 existing Chroma tests pass. However, 4 critical blockers prevent merge: (1) **Zscaler SSL regression** — PR #884's `getCombinedCertPath()` and SSL env var injection are completely removed, breaking enterprise users behind corporate proxies; (2) **No tests** for 290-line ChromaServerManager (process spawn, heartbeat polling, cross-platform shutdown); (3) **Merge conflicts** with PRs #769, #884, #887 already merged to main; (4) **macOS untested** despite being primary dev platform. Additional concerns: ~180MB memory overhead, port 8000 default conflicts, Python dependency not actually removed (shifted to npx chroma run). Left detailed review comment requesting rebase, Zscaler SSL port, ChromaServerManager tests, and macOS verification.

Auto Run Docs/PR-Triage/PR-Triage-10.md

@@ -1,44 +0,0 @@
-# Phase 10: Documentation Batch
-
-Quick wins — docs PRs are low-risk and can be merged rapidly after basic review.
-
-## README Fixes (merge quickly)
-
-- [x] Review and merge PR #953 (`Fix formatting in README for plugin commands` by @Leonard013). Single file, formatting fix. Steps: (1) `gh pr checkout 953` (2) Quick review for correctness (3) `gh pr merge 953 --rebase --delete-branch`
-  - **Merged 2026-02-06.** Removed `>` blockquote characters from inside code blocks in README.md that prevented copy-paste of plugin install commands.
-
-- [x] Review and merge PR #898 (`docs: update README.ko.md` by @youngsu5582). Single file, Korean README. Steps: (1) `gh pr checkout 898` (2) Quick review (3) `gh pr merge 898 --rebase --delete-branch`
-  - **Merged 2026-02-06.** Fixed Korean markdown hyperlinks by adding spaces between URLs and Korean postpositions (에서, 의, 를) to prevent markdown from including Korean characters in the URL. 2 lines changed in `docs/i18n/README.ko.md`.
-
-- [x] Review and merge PR #864 (`docs: update README.ja.md` by @eltociear). Single file, Japanese README. Steps: (1) `gh pr checkout 864` (2) Quick review (3) `gh pr merge 864 --rebase --delete-branch`
-  - **Merged 2026-02-06.** Added spaces between markdown link closings and Japanese postposition `を参照` in 4 locations to prevent markdown from including Japanese characters in URLs. Also added missing newline at end of file. 5 lines changed in `docs/i18n/README.ja.md`.
-
-- [x] Review and merge PR #637 (`docs: fix ja readme of md render error` by @WuMingDao). Single file render fix. Steps: (1) `gh pr checkout 637` (2) Quick review (3) `gh pr merge 637 --rebase --delete-branch`
-  - **Merged 2026-02-06.** 5 of 6 original changes were already applied by PR #864. Git's rebase merge cleanly resolved the overlap, applying only the remaining fix: added spaces around bold markdown in the Ragtime license note (`は **PolyForm...** の下で`) to fix rendering. 1 line changed in `docs/i18n/README.ja.md`.
-
-- [x] Review and merge PR #636 (`docs: fix zh readme of md render error` by @WuMingDao). Single file render fix. Steps: (1) `gh pr checkout 636` (2) Quick review (3) `gh pr merge 636 --rebase --delete-branch`
-  - **Merged 2026-02-06.** Added spaces around bold markdown links (`**[text](url)**` → `**[text](url)** `) in 4 locations to fix Chinese markdown rendering where characters were absorbed into URLs. Also added missing newline at end of file. 5 lines changed in `docs/i18n/README.zh.md`.
-
-## Larger Docs PRs
-
-- [x] Review PR #894 (`docs: update documentation links to official website` by @fengluodb). 29 files — updates links across all READMEs. Steps: (1) `gh pr checkout 894` (2) Verify all links point to correct docs.claude-mem.ai pages (3) Spot-check a few files (4) If links are correct: `gh pr merge 894 --rebase --delete-branch`
-  - **Merged 2026-02-06.** Updated documentation links in README.md and all 28 i18n README files from relative `docs/` path to `https://docs.claude-mem.ai/`. Also localized description text from "Browse markdown docs on GitHub" to "Browse on official website" in each language. 29 files, 1 line changed per file. CI passed (Greptile Review).
-
-- [x] Review PR #907 (`i18n: add Traditional Chinese (zh-TW) README translation` by @PeterDaveHello). 31 files. Steps: (1) `gh pr checkout 907` (2) Verify translation file structure matches existing i18n pattern (3) Check that only translation files are added, no source changes (4) If clean: `gh pr merge 907 --rebase --delete-branch`
-  - **Merged 2026-02-06.** Added full Traditional Chinese (zh-TW) README translation (311 lines) at `docs/i18n/README.zh-tw.md`. Added `🇹🇼 繁體中文` language nav link to all 29 existing READMEs plus main README.md. Updated `package.json` to include `zh-tw` in tier1 translation script. 31 files changed, 341 additions. CI passed (Greptile Review).
-
-- [x] Review PR #691 (`feat: Add Urdu language support` by @yasirali646). 34 files. Steps: (1) `gh pr checkout 691` (2) Verify translation quality (spot-check a few sections) (3) Check file structure matches other language READMEs (4) If clean: `gh pr merge 691 --rebase --delete-branch`
-  - **Merged 2026-02-06.** Added full Urdu (ur) README translation (311 lines) at `docs/i18n/README.ur.md` with RTL `<section dir="rtl">` wrapper and LTR language nav. Added `🇵🇰 اردو` language nav link to all 29 existing READMEs plus main README.md. Added Urdu mode file `plugin/modes/code--ur.json` matching existing mode structure. Updated translate-readme scripts (`cli.ts`, `index.ts`) with Urdu entry. Added Urdu to `docs/public/modes.mdx` table. 34 files changed, 368 additions. No CI checks configured.
-
-## Windows-Specific Docs
-
-- [x] Review and merge PR #919 (`docs: add Windows setup note for npm not recognized error` by @kamran-khalid-v9). Steps: (1) `gh pr checkout 919` (2) Review the note — should explain PATH configuration for npm on Windows (3) If helpful: `gh pr merge 919 --rebase --delete-branch`
-  - **Merged 2026-02-06.** Added 11-line Windows setup note to README.md explaining how to resolve "npm is not recognized as the name of a cmdlet" error by installing Node.js and ensuring npm is on PATH. CI passed (Greptile Review). Fixes #908.
-
-- [x] Review and merge PR #882 (`Add Windows local development notes to README` by @namratab18). Single file. Steps: (1) `gh pr checkout 882` (2) Quick review (3) `gh pr merge 882 --rebase --delete-branch`
-  - **Closed 2026-02-06 (not merged).** Content was too generic — the 3 steps (install Git, clone repo, run project) aren't Windows-specific and duplicate the existing Development Guide link. README already has a "Windows Setup Notes" section (from PR #919) covering the most common Windows issue (npm PATH). Greptile review also flagged awkward placement and vague instructions.
-
-## Issue Templates
-
-- [x] Review and merge PR #970 (`fix: update bug and feature request templates to include duplicate check` by @bmccann36). 3 files (issue templates). Steps: (1) `gh pr checkout 970` (2) Review templates — adding a duplicate check reminder is good practice (3) `gh pr merge 970 --rebase --delete-branch`
-  - **Merged 2026-02-06.** Added "Before submitting" section with duplicate check checkbox (`I searched existing issues and confirmed this is not a duplicate`) to top of both `bug_report.md` and `feature_request.md` issue templates. Also added `.idea/` to `.gitignore` and fixed missing newline at EOF. 3 files changed, 16 additions. CI passed (Greptile Review). Hard-coded upstream issues link is intentional per author — fork users should search upstream, not their empty fork tracker.

Auto Run Docs/PR-Triage/PR-Triage-11.md

@@ -1,48 +0,0 @@
-# Phase 11: Miscellaneous Bug Fixes
-
-Standalone bug fixes that don't group neatly into other phases.
-
-## Parser Fixes
-
-- [x] Review PR #835 (`fix: handle nested XML tags in parser extractField and extractArrayElements` by @Glucksberg). File: `src/sdk/parser.ts`. Nested XML tags break field extraction. Steps: (1) `gh pr checkout 835` (2) Review regex/parser changes — should handle `<field><inner>content</inner></field>` patterns (3) Run `npm run build` (4) If correct: `gh pr merge 835 --rebase --delete-branch`
-  - **Merged.** Clean regex fix: `[^<]*` → `[\s\S]*?` (non-greedy) in `extractField()` and `extractArrayElements()`. Also adds empty element filtering. Greptile 5/5 confidence. Build failure is pre-existing (dompurify dep), not introduced by this PR. TypeScript compilation passes for parser.ts.
-
-- [x] Review PR #862 (`fix: handle missing assistant messages gracefully in transcript parser` by @DennisHartrampf). File: `src/shared/transcript-parser.ts`. Missing assistant messages cause parser crash. Steps: (1) `gh pr checkout 862` (2) Review — should skip or handle gracefully, not crash (3) Run `npm run build` (4) If clean: `gh pr merge 862 --rebase --delete-branch`
-  - **Merged.** One-line fix: `throw new Error(...)` → `return ''` in `extractLastMessage()` when no message of requested role is found. Consistent with the function's existing behavior (already returns `''` at line 64 for found-but-empty cases). Fixes crash in summarize hook when user exits before assistant responds.
-
-## Gemini Model Name
-
-- [x] Review PR #831 (`fix: correct Gemini model name from gemini-3-flash to gemini-3-flash-preview` by @Glucksberg). Files: 12 files including GeminiAgent.ts, docs, UI. Steps: (1) `gh pr checkout 831` (2) Verify the correct model name from Gemini docs (is it `gemini-3-flash-preview` or something else as of today?) (3) If model name is correct and changes are sound: `gh pr merge 831 --rebase --delete-branch`
-  - **Merged.** Verified `gemini-3-flash-preview` is the correct model ID per Google's official [Gemini API docs](https://ai.google.dev/gemini-api/docs/models) — `gemini-3-flash` does not exist. Cherry-picked onto main (build artifact conflicts only, source merged cleanly). 9 files updated: type definition, RPM limits, model validation, settings, UI dropdown, docs, and tests. Greptile review noted a pre-existing unrelated naming mismatch in docs (`CLAUDE_MEM_GEMINI_BILLING_ENABLED` vs actual `CLAUDE_MEM_GEMINI_RATE_LIMITING_ENABLED`).
-
-## Config/Environment
-
-- [x] Review PR #634 (`fix: respect CLAUDE_CONFIG_DIR for plugin paths (#626)` by @Kuroakira). Files: 14 files across paths, hooks, and services. Steps: (1) `gh pr checkout 634` (2) Review — should use `CLAUDE_CONFIG_DIR` env var instead of hardcoded `~/.claude/` path (3) Large changeset — verify it doesn't break default behavior when env var is not set (4) Run `npm run build` (5) If clean: `gh pr merge 634 --rebase --delete-branch`
-  - **Cherry-picked onto main.** PR had build artifact merge conflicts (plugin/scripts/* — minified bundles), but all 6 source changes applied cleanly. Adds `MARKETPLACE_ROOT` constant to `paths.ts`, updates `HealthMonitor.ts`, `worker-utils.ts`, `BranchManager.ts`, `CursorHooksInstaller.ts`, and `ObservationCompiler.ts` to use centralized constants instead of hardcoded `homedir() + '.claude'` paths. Backwards compatible — defaults to `~/.claude` when `CLAUDE_CONFIG_DIR` is not set. TypeScript compilation passes for all modified files. Build failure is pre-existing (dompurify dep). Fixes #626.
-
-- [x] Review PR #712 (`Fix environment variables` by @cjpeterein). Files: SettingsDefaultsManager.ts + build artifacts + tests. Steps: (1) `gh pr checkout 712` (2) Review — what env var fix? Check the diff for specifics (3) Run `npm run build` (4) If clean and focused: `gh pr merge 712 --rebase --delete-branch`
-  - **Cherry-picked onto main.** Adds `applyEnvOverrides()` method ensuring env vars take highest priority: `env > file > defaults`. Applied to all 3 return paths in `loadFromFile()` (missing file, normal load, error fallback). 6 test cases added and passing. Enables runtime configuration overrides for containerized deployments and CI/CD without modifying settings files. Build artifacts had merge conflicts (minified bundles) — source changes applied cleanly.
-
-- [x] Review PR #524 (`fix: add minimum bun version check to smart-install.js` by @quicktime). File: `plugin/scripts/smart-install.js`. Steps: (1) `gh pr checkout 524` (2) Review version check logic — what minimum version? Is it still relevant? (3) If clean: `gh pr merge 524 --rebase --delete-branch`
-  - **Merged.** Adds `MIN_BUN_VERSION = '1.1.14'` check with auto-upgrade via `bun upgrade`. Clean semver `compareVersions()` function, `isBunVersionSufficient()` check inserted between bun install and uv install steps. Minimum version is justified: bun 1.1.14+ required for `.changes` property on SQLite `.run()` and multi-statement SQL support (1.0.26+). Falls back gracefully with manual upgrade instructions if auto-upgrade fails. Fixes #519.
-
-- [x] Review PR #771 (`fix: handle stdin unavailability and timeout to prevent hook hangs` by @rajivsinclair). File: `src/cli/stdin-reader.ts`. Steps: (1) `gh pr checkout 771` (2) Review — stdin may not be available in all environments (CI, some Windows configs) (3) Should add timeout and graceful fallback (4) Run `npm run build` (5) If clean: `gh pr merge 771 --rebase --delete-branch`
-  - **Merged.** Replaces naive `stdin.on('end')` listener (which hangs when Claude Code doesn't close stdin) with JSON self-delimiting detection — tries `JSON.parse()` after each chunk and resolves immediately on valid JSON. Adds `isStdinAvailable()` guard for Bun EINVAL crash (#646), 30s safety timeout for malformed input, and graceful error handling (returns `undefined` instead of crashing). Fixes #727, addresses #646. TypeScript compilation clean.
-
-## Cursor Integration
-
-- [x] Review PR #721 (`fix(cursor): use bun runtime and fix hooks directory detection` by @polux0). Files: 5 cursor-related files. Steps: (1) `gh pr checkout 721` (2) Review Cursor hook changes — should use bun-runner.js pattern (consistent with v9.0.17) (3) Run `npm run build` (4) If compatible with current architecture: `gh pr merge 721 --rebase --delete-branch`
-  - **Cherry-picked onto main.** Source changes from `CursorHooksInstaller.ts` applied cleanly (commit 8030c44a). Fixes two Cursor standalone setup bugs: (1) `findCursorHooksDir()` now checks for `hooks.json` in unified CLI mode, not just legacy shell scripts — prevents "Could not find cursor-hooks directory" error for standalone Cursor users. (2) Hook commands now use bun instead of node, fixing `bun:sqlite` dependency crash. Added `findBunPath()` for cross-platform bun detection with PATH fallback. Build artifacts skipped (pre-existing dompurify dep issue). Dev log docs (`CURSOR-SETUP-BUGS-AND-FIXES.md`, `CURSOR-STANDALONE-SETUP-LOG.md`) not merged.
-
-## Database
-
-- [x] Review PR #889 (`fix(db): prevent FK constraint failures on worker restart` by @Et9797). File: `src/services/sqlite/...` (FK constraints). Steps: (1) `gh pr checkout 889` (2) Review — FK constraint failures on restart suggest orphaned references. Should the fix be proper cleanup or deferred FK checks? (3) Run `npm run build` (4) If clean: `gh pr merge 889 --rebase --delete-branch`
-  - **Cherry-picked onto main.** Comprehensive fix for FK constraint violations causing infinite retry loops and high CPU usage (#846). Core fix: `ensureMemorySessionIdRegistered()` guard ensures parent `sdk_sessions` row has correct `memory_session_id` before child `observations` INSERT. Schema migration 21 adds `ON UPDATE CASCADE` to FK constraints so child rows follow parent updates. Also includes claim-confirm queue pattern (prevents message loss on crash), spawn deduplication (prevents duplicate generator starts), and unrecoverable error detection (breaks infinite restart loops). Build artifacts skipped (stale base), path fixes already merged via PR #634. All 838 tests passing, 4 new FK constraint tests + 8 zombie prevention tests added. 20 source/test files changed.
-
-- [x] Review PR #833 (`fix: add PRAGMA foreign_keys to cleanup-duplicates.ts` by @Glucksberg). Steps: (1) `gh pr checkout 833` (2) Check if the cleanup script context still exists and if PRAGMA foreign_keys is needed there (3) v8.5.6 fixed FK constraints — this may be stale. If so: `gh pr close 833 --comment "FK constraint issues were addressed in v8.5.6. If a specific scenario remains, please describe and reopen. Thank you!"`
-  - **Closed as stale.** The PR references non-existent `observation_files` and `observation_concepts` tables. In the current schema, `observations` is a child of `sdk_sessions` and has no children of its own — so `PRAGMA foreign_keys = ON` before deleting observations has no CASCADE effect. FK constraint issues were comprehensively addressed in v8.5.6 (PR #889: `ensureMemorySessionIdRegistered()` guard, `ON UPDATE CASCADE` schema migration, claim-confirm queue pattern).
-
-## Session Complete Hook
-
-- [x] Review PR #844 (`fix: add session-complete handler and hook to enable orphan reaper cleanup` by @thusdigital). Steps: (1) `gh pr checkout 844` (2) Review — does the orphan reaper need a session-complete signal to work? Check if the 5-min reaper interval is sufficient without it. (3) If the hook adds meaningful cleanup triggers: `gh pr merge 844 --rebase --delete-branch`. If reaper already handles this: close.
-  - **Cherry-picked onto main.** The orphan reaper was correctly implemented (5-min interval in ProcessRegistry.ts) but was ineffective because sessions were never removed from the active sessions map after summarize — so the reaper always saw all PIDs as "active" and never cleaned up. This caused zombie process accumulation (reported: 39+ processes, ~10GB on macOS after a single restart). PR adds session-complete as Stop phase 2 hook (after summarize, 30s timeout) that calls `POST /api/sessions/complete` to remove sessions from the active map via `SessionCompletionHandler.completeByDbId()`. 5 source files changed (new handler, handler registry, route, hooks.json, CLI help). Build artifacts skipped (stale base). 838 tests passing. Fixes #842.

Auto Run Docs/PR-Triage/PR-Triage-12.md

@@ -1,39 +0,0 @@
-# Phase 12: Feature PRs — Evaluation & Decision
-
-These are feature PRs that need product/architectural decisions. Each should be evaluated against the project roadmap and YAGNI principles.
-
-## Provider Integrations
-
-Multiple community members want to add provider support. Evaluate whether the project should support more providers or focus on stability.
-
-- [x] Evaluate PR #808 (`feat: Add AnthropicAPIAgent for direct API observation processing` by @MrSaneApps, 4 files). **CLOSED.** Memory concerns (the core motivation) were already addressed by merged PR #806. Having two Anthropic providers (SDK + direct API) creates user confusion and maintenance burden. Claude SDK via CLI auth remains the recommended path. Closed with detailed explanation thanking the contributor.
-
-- [x] Evaluate PR #786 (`feat: add GLM provider and custom Anthropic-compatible API support` by @Zorglub4242, 13 files). **CLOSED.** Three issues: (1) `process.env` mutation is a concurrency bug — env vars leak between sessions since the worker handles multiple sessions on one process. (2) GLM preset is YAGNI — a generic custom provider option would cover GLM users without a dedicated preset. (3) Custom Anthropic-compatible API support is a good concept but needs subprocess-scoped env vars, not global mutation. Invited contributor to re-submit a focused custom-provider-only PR.
-
-- [x] Evaluate PR #644 (`feat: Add OpenAI provider support` by @niteeshm, 10 files). **CLOSED.** OpenAI models are already accessible via the OpenRouter provider, which uses the same OpenAI-compatible chat/completions API format. Adding a dedicated OpenAI agent (491 lines) would create significant code duplication with OpenRouterAgent. A community commenter (@kiwina) independently flagged the same overlap. Suggested contributor could instead PR a configurable base URL for OpenRouter to support Azure/custom endpoints.
-
-- [x] Evaluate PR #680 (`feat(openrouter): multi-model configuration with automatic fallback` by @RyderFreeman4Logos, 28 files). **CLOSED.** Three issues: (1) Bundles 5+ distinct features (multi-model fallback, provider fallback chain, configurable base URL, settings hot-reload, Gemini 3 default) into one PR — each should be separate. (2) Deletes content from 12+ CLAUDE.md documentation files (~1,200 lines of project docs removed), which is destructive and unrelated to the feature. (3) Multi-model fallback is YAGNI — most users configure a single model. Invited contributor to re-submit a focused configurable-base-URL-only PR.
-
-- [x] Evaluate PR #746 (`feat: add OpenCode platform support` by @MattMagg, 12 files). **CLOSED — resubmit requested.** Platform-agnostic support IS a goal (the adapter architecture was designed for it), and the core adapter code (26 lines) is clean and follows the Cursor adapter pattern. However, the PR includes build artifacts (worker-service.cjs, mcp-server.cjs), planning scratch docs committed to root, a settings.json whitespace change, and an `.opencode/` plugin directory with maintenance implications. Requested a focused re-submission with just the adapter source, router change, README update, and docs.
-
-- [x] Evaluate PR #860 (`feat: add Clawdbot/moltbot environment detection and compatibility mode` by @janitooor, 3 files). **CLOSED.** Three issues: (1) YAGNI — no evidence of user demand for Clawdbot compatibility, and the PR was a bot-generated "autonomous contribution by Legba." (2) Dead code — the detection utilities are standalone and never integrated into any hook, service, or handler. (3) Documentation references non-existent API endpoints and settings. If real conflicts surface from user reports, a focused, integrated fix would be welcome.
-
-## Memory Features
-
-- [x] Evaluate PR #662 (`feat(mcp): add save_memory tool for manual memory storage` by @darconada, 8 files). **MERGED (cherry-picked to main).** Manual memory storage aligns with the project philosophy — automatic capture handles 80% of cases, manual save handles the 20% where users want explicit control (Issue #645). Source changes applied directly (PR had merge conflicts in compiled .cjs build artifacts only). Implementation is clean: MCP tool definition, POST /api/memory/save endpoint via MemoryRoutes.ts, getOrCreateManualSession() in SessionStore, README updates. Minor fix: changed logger component from unregistered 'MEMORY' to 'HTTP'/'CHROMA'. Closes #645.
-
-- [x] Evaluate PR #920 (`feat: add project exclusion setting` by @Spunky84, 7 files) and PR #699 (`feat: add folder exclude setting for CLAUDE.md generation` by @leepokai, 2 files). **BOTH MERGED (cherry-picked to main).** These solve complementary problems, not the same problem: (1) PR #920 adds `CLAUDE_MEM_EXCLUDED_PROJECTS` — glob patterns to exclude entire projects from ALL tracking (privacy/confidentiality). Well-tested (11 unit tests), clean glob-to-regex implementation, early-exit in session-init and observation handlers. Minor cleanup: removed unused SessionRoutes import and unexported internal helper. (2) PR #699 adds `CLAUDE_MEM_FOLDER_MD_EXCLUDE` — JSON array of paths to exclude from CLAUDE.md file generation (build tool compatibility). Solves confirmed issues: SwiftUI/Xcode build conflicts, drizzle kit migration failures (3 separate commenters). Closes #620. Both had merge conflicts with current main, so changes were applied directly rather than git-merged.
-
-## Architectural Changes
-
-- [x] Evaluate PR #660 (`feat: add network mode for multi-agent deployments` by @nycterent, 42 files). **CLOSED.** Three issues: (1) Deletes ~1,100 lines of CLAUDE.md documentation across 19 files, replacing content with `*No recent activity*` — same destructive pattern as PR #680. (2) Bundles 4+ distinct features: network mode, OpenCode integration (already closed in PR #746), Basic Memory import script, remote MCP wrapper. (3) The actual network mode feature (WORKER_BIND/WORKER_HOST separation) is only ~50 lines and is a solid concept. Invited contributor to re-submit a focused network-mode-only PR without documentation deletions or bundled features.
-
-- [x] Evaluate PR #968 (`Migrate from SQLite to memU hierarchical memory backend` by @minhlucvan, 55 files). **ALREADY CLOSED (by author).** PR was closed by @minhlucvan on Feb 5, 2026. Greptile's automated review gave it a 0/5 confidence score — the PR deleted all SQLite files but didn't update the 30+ files that import them, meaning the application would fail immediately at runtime. The PR description claimed features (IStorageBackend interface, BackendFactory, SqliteAdapter) that didn't exist in the actual code. Additionally, replacing SQLite with an external dependency violates the project's zero-dependency, portable architecture. No action needed — author self-closed.
-
-- [x] Evaluate PR #854 (`feat: Pro cloud sync integration with Supabase + Pinecone` by @bigph00t, 35 files). **CLOSED — premature, hold for later.** @bigph00t is a trusted contributor (4 merged PRs including #806 zombie process fix and #813 path format fix), and the architecture is well-considered (SyncProvider abstraction, CloudSync with SQLite fallback, secure ProConfig with 0600 permissions). However, five issues prevent merging now: (1) The Pro API backend (`claude-mem-pro.vercel.app`) returns 404 — merging client code before the server exists would leave users with a broken `/pro-setup` flow. (2) Bundles already-merged changes — `ProcessRegistry.ts` (from PR #806) and `path-utils.ts` (from PR #813) already exist on main, creating conflicts. (3) Includes built artifacts (`worker-service.cjs`, `mcp-server.cjs`, `viewer-bundle.js`). (4) CLAUDE.md states Pro integration points should be "minimal: settings for license keys, tunnel provisioning logic" — this PR adds 3,907 lines including dual storage paths in `ResponseProcessor.ts`, which is a substantial core architecture change. (5) Version bumps (9.0.6→9.0.10) and CHANGELOG entries don't match current release history. Invited contributor to resubmit a clean PR rebased on main when the Pro backend is live.
-
-## Owner's PRs
-
-- [x] Review PR #863 (`feat: implement ragtime email investigation with self-iteration and cleanup` by @thedotmack, 2 files). **MERGED.** Owner's PR. Transforms ragtime from a placeholder stub into a functional email investigation batch processor. Key improvements: replaces hardcoded absolute paths with configurable environment variables (CONFIG object with 7 settings), adds `cleanupOldTranscripts()` to prevent transcript buildup, proper `main()` function with error handling, `getFilesToProcess()` with directory validation and file limit, structured `processFile()` with message parsing, removes debugging cruft. README updated from "not yet implemented" to comprehensive usage documentation with configuration table. Greptile review: 4/5 confidence, safe to merge. Both automated reviews passed.
-
-- [x] Review PR #657 (`feat: add generate/clean CLI commands with cross-platform support` by @thedotmack, 100 files). **MERGED (cherry-picked to main).** Owner's PR, 224 commits behind main. Cherry-picked 3 source changes: (1) New `src/cli/claude-md-commands.ts` with `generateClaudeMd()` and `cleanClaudeMd()` — uses shared `isDirectChild` from `path-utils.ts` (DRY improvement over PR original). (2) Worker service `generate`/`clean` case handlers with `--dry-run` support. (3) `CLAUDE_MD` logger component type. Skipped: 91 stale CLAUDE.md deletions, `.claude/plans/` dev artifact, `smart-install.js` auto-injection of shell aliases (modifies `~/.zshrc` without consent), and `claude-md-utils.ts`/`SettingsDefaultsManager.ts` changes that would have reverted safety guards and exclusion settings merged in later PRs. Tests: 857 pass, 3 skip, 1 pre-existing flaky timeout.

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`

PLAN.md

@@ -1,154 +0,0 @@
-# Plan: Address PR #856 Review Feedback
-
-## Summary of Review Feedback
-
-Multiple reviewers identified the same core issues:
-
-1. **Race Condition in Idle Detection** (Medium-High Priority)
-   - When timeout fires at 3:00 but last message was at 2:59, `idleDuration` is 1 second, check fails
-   - Need to either remove redundant check or reset `lastActivityTime` on timeout
-
-2. **Missing Test Coverage** (High Priority)
-   - No tests for SessionQueueProcessor timeout logic
-   - Critical fix for high-impact bug (79 processes, 13.4GB swap)
-
-3. **Minor: Optional Chaining** (Low Priority)
-   - Use `onIdleTimeout?.()` instead of `if (onIdleTimeout) { onIdleTimeout() }`
-
-4. **Minor: Logging Enhancement** (Low Priority)
-   - Add timeout threshold to log message for debugging
-
----
-
-## Phase 0: Documentation Discovery (COMPLETE)
-
-### Sources Consulted
-- PR #856 comments from claude, greptile-apps reviewers
-- `src/services/queue/SessionQueueProcessor.ts` (current implementation)
-
-### Allowed APIs
-- `waitForMessage(signal, timeoutMs)` → Promise<boolean>
-- `logger.info('SESSION', ...)` for logging
-
-### The Fix Strategy
-
-The reviewers suggest two options:
-
-**Option A**: Remove redundant check since `waitForMessage` enforces timeout
-```typescript
-if (!receivedMessage && !signal.aborted) {
-  // Timeout occurred - exit gracefully
-  const idleDuration = Date.now() - lastActivityTime;
-  logger.info('SESSION', 'Exiting queue iterator due to idle timeout', { ... });
-  onIdleTimeout?.();
-  return;
-}
-```
-
-**Option B**: Reset `lastActivityTime` on timeout to handle edge cases
-```typescript
-if (!receivedMessage && !signal.aborted) {
-  const idleDuration = Date.now() - lastActivityTime;
-  if (idleDuration >= IDLE_TIMEOUT_MS) {
-    logger.info('SESSION', 'Exiting...', { ... });
-    onIdleTimeout?.();
-    return;
-  }
-  // CRITICAL: Reset timer since we know queue is empty now
-  lastActivityTime = Date.now();
-}
-```
-
-**Decision**: Use Option B - it's defensive and handles spurious wakeups correctly.
-
----
-
-## Phase 1: Fix Race Condition in SessionQueueProcessor
-
-### What to Implement
-Fix the idle timeout logic to reset `lastActivityTime` when timeout occurs but duration check fails.
-
-### Tasks
-1. In `createIterator()` at lines 50-62, add `lastActivityTime = Date.now()` after the duration check fails
-2. Use optional chaining for `onIdleTimeout?.()`
-3. Add timeout threshold to log message
-
-### Pattern to Follow
-```typescript
-if (!receivedMessage && !signal.aborted) {
-  const idleDuration = Date.now() - lastActivityTime;
-  if (idleDuration >= IDLE_TIMEOUT_MS) {
-    logger.info('SESSION', 'Idle timeout reached, triggering abort to kill subprocess', {
-      sessionDbId,
-      idleDurationMs: idleDuration,
-      thresholdMs: IDLE_TIMEOUT_MS
-    });
-    onIdleTimeout?.();
-    return;
-  }
-  // Reset timer on spurious wakeup - queue is empty but duration check failed
-  lastActivityTime = Date.now();
-}
-```
-
-### Verification
-```bash
-npm run build
-grep -A10 "idleDuration >= IDLE_TIMEOUT_MS" src/services/queue/SessionQueueProcessor.ts
-```
-
----
-
-## Phase 2: Add Unit Tests for SessionQueueProcessor
-
-### What to Implement
-Create test file covering the idle timeout behavior.
-
-### Test Cases Required
-1. Iterator exits after idle timeout when no messages arrive
-2. `onIdleTimeout` callback is invoked on timeout
-3. Message arrival resets the idle timer
-4. Abort signal takes precedence over timeout
-5. Event listener cleanup happens correctly
-
-### Location
-`tests/services/queue/SessionQueueProcessor.test.ts`
-
-### Verification
-```bash
-npm run test -- SessionQueueProcessor
-```
-
----
-
-## Phase 3: Build and Verify
-
-### Tasks
-1. Run `npm run build` - verify no TypeScript errors
-2. Run tests to ensure timeout behavior works
-3. Commit changes to fix/observer-idle-timeout branch
-4. Push to update PR #856
-
-### Verification
-```bash
-npm run build
-npm run test
-git diff --stat
-```
-
----
-
-## Phase 4: Update PR Description
-
-### Tasks
-1. Update test plan checkboxes in PR description
-2. Add note about race condition fix
-
----
-
-## Summary of Changes
-
-| File | Change |
-|------|--------|
-| `src/services/queue/SessionQueueProcessor.ts` | Fix race condition, optional chaining, enhanced logging |
-| `tests/services/queue/SessionQueueProcessor.test.ts` | New test file for timeout behavior |

README.md

@@ -24,11 +24,12 @@
   <a href="docs/i18n/README.zh.md">🇨🇳 中文</a> •
   <a href="docs/i18n/README.zh-tw.md">🇹🇼 繁體中文</a> •
   <a href="docs/i18n/README.ja.md">🇯🇵 日本語</a> •
+  <a href="docs/i18n/README.pt.md">🇵🇹 Português</a> •
   <a href="docs/i18n/README.pt-br.md">🇧🇷 Português</a> •
   <a href="docs/i18n/README.ko.md">🇰🇷 한국어</a> •
   <a href="docs/i18n/README.es.md">🇪🇸 Español</a> •
   <a href="docs/i18n/README.de.md">🇩🇪 Deutsch</a> •
-  <a href="docs/i18n/README.fr.md">🇫🇷 Français</a>
+  <a href="docs/i18n/README.fr.md">🇫🇷 Français</a> •
   <a href="docs/i18n/README.he.md">🇮🇱 עברית</a> •
   <a href="docs/i18n/README.ar.md">🇸🇦 العربية</a> •
   <a href="docs/i18n/README.ru.md">🇷🇺 Русский</a> •
@@ -38,6 +39,7 @@
   <a href="docs/i18n/README.tr.md">🇹🇷 Türkçe</a> •
   <a href="docs/i18n/README.uk.md">🇺🇦 Українська</a> •
   <a href="docs/i18n/README.vi.md">🇻🇳 Tiếng Việt</a> •
+  <a href="docs/i18n/README.tl.md">🇵🇭 Tagalog</a> •
   <a href="docs/i18n/README.id.md">🇮🇩 Indonesia</a> •
   <a href="docs/i18n/README.th.md">🇹🇭 ไทย</a> •
   <a href="docs/i18n/README.hi.md">🇮🇳 हिन्दी</a> •
@@ -118,6 +120,18 @@ Start a new Claude Code session in the terminal and enter the following commands
 
 Restart Claude Code. 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.
+
+### 🦞 OpenClaw Gateway
+
+Install claude-mem as a persistent memory plugin on [OpenClaw](https://openclaw.ai) gateways with a single command:
+
+```bash
+curl -fsSL https://install.cmem.ai/openclaw.sh | bash
+```
+
+The installer handles dependencies, plugin setup, AI provider configuration, worker startup, and optional real-time observation feeds to Telegram, Discord, Slack, and more. See the [OpenClaw Integration Guide](https://docs.claude-mem.ai/openclaw-integration) for details.
+
 **Key Features:**
 
 - 🧠 **Persistent Memory** - Context survives across sessions
@@ -184,7 +198,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:**
 
@@ -197,7 +211,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:**
@@ -205,8 +218,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:**
 
@@ -218,9 +229,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.

docs/bug-fixes/windows-spaces-issue.md

@@ -0,0 +1,98 @@
+---
+Title: Bug: SDK Agent fails on Windows when username contains spaces
+---
+
+## Bug Report
+
+**Summary:** Claude SDK Agent fails to start on Windows when the user's path contains spaces (e.g., `C:\Users\Anderson Wang\`), causing PostToolUse hooks to hang indefinitely.
+
+**Severity:** High - Core functionality broken
+
+**Affected Platform:** Windows only
+
+---
+
+## Symptoms
+
+PostToolUse hook displays `(1/2 done)` indefinitely. Worker logs show:
+
+```
+ERROR [SESSION] Generator failed {provider=claude, error=Claude Code process exited with code 1}
+ERROR [SESSION] Generator exited unexpectedly
+```
+
+---
+
+## Root Cause
+
+Two issues in the Windows code path:
+
+1. **`SDKAgent.ts`** - Returns full auto-detected path with spaces:
+   ```
+   C:\Users\Anderson Wang\AppData\Roaming\npm\claude.cmd
+   ```
+
+2. **`ProcessRegistry.ts`** - Node.js `spawn()` cannot directly execute `.cmd` files when the path contains spaces
+
+---
+
+## Proposed Fix
+
+### File 1: `src/services/worker/SDKAgent.ts`
+
+On Windows, prefer `claude.cmd` via PATH instead of full auto-detected path:
+
+```typescript
+// On Windows, prefer "claude.cmd" (via PATH) to avoid spawn issues with spaces in paths
+if (process.platform === 'win32') {
+  try {
+    execSync('where claude.cmd', { encoding: 'utf8', windowsHide: true, stdio: ['ignore', 'pipe', 'ignore'] });
+    return 'claude.cmd'; // Let Windows resolve via PATHEXT
+  } catch {
+    // Fall through to generic error
+  }
+}
+```
+
+### File 2: `src/services/worker/ProcessRegistry.ts`
+
+Use `cmd.exe /d /c` wrapper for .cmd files on Windows:
+
+```typescript
+const useCmdWrapper = process.platform === 'win32' && spawnOptions.command.endsWith('.cmd');
+
+if (useCmdWrapper) {
+  child = spawn('cmd.exe', ['/d', '/c', spawnOptions.command, ...spawnOptions.args], {
+    cwd: spawnOptions.cwd,
+    env: spawnOptions.env,
+    stdio: ['pipe', 'pipe', 'pipe'],
+    signal: spawnOptions.signal,
+    windowsHide: true
+  });
+}
+```
+
+---
+
+## Why This Works
+
+- **PATHEXT Resolution:** Windows searches PATH and tries each extension in PATHEXT automatically
+- **cmd.exe wrapper:** Properly handles paths with spaces and argument passing
+- **Avoids shell parsing:** Using direct arguments instead of `shell: true` prevents empty string misparsing
+
+---
+
+## Testing
+
+Verified on Windows 11 with username containing spaces:
+- PostToolUse hook completes successfully
+- Observations are stored to database
+- No more "process exited with code 1" errors
+
+---
+
+## Additional Notes
+
+- Maintains backward compatibility with `CLAUDE_CODE_PATH` setting
+- No impact on non-Windows platforms
+- Related to Issue #733 (credential isolation) - separate fix

docs/i18n/README.tl.md

@@ -0,0 +1,328 @@
+🌐 Ito ay isang awtomatikong pagsasalin. Malugod na tinatanggap ang mga pagwawasto mula sa komunidad!
+
+---
+<h1 align="center">
+  <br>
+  <a href="https://github.com/thedotmack/claude-mem">
+    <picture>
+      <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/thedotmack/claude-mem/main/docs/public/claude-mem-logo-for-dark-mode.webp">
+      <source media="(prefers-color-scheme: light)" srcset="https://raw.githubusercontent.com/thedotmack/claude-mem/main/docs/public/claude-mem-logo-for-light-mode.webp">
+      <img src="https://raw.githubusercontent.com/thedotmack/claude-mem/main/docs/public/claude-mem-logo-for-light-mode.webp" alt="Claude-Mem" width="400">
+    </picture>
+  </a>
+  <br>
+</h1>
+
+<p align="center">
+  <a href="README.zh.md">🇨🇳 中文</a> •
+  <a href="README.zh-tw.md">🇹🇼 繁體中文</a> •
+  <a href="README.ja.md">🇯🇵 日本語</a> •
+  <a href="README.pt-br.md">🇧🇷 Português</a> •
+  <a href="README.ko.md">🇰🇷 한국어</a> •
+  <a href="README.es.md">🇪🇸 Español</a> •
+  <a href="README.de.md">🇩🇪 Deutsch</a> •
+  <a href="README.fr.md">🇫🇷 Français</a> •
+  <a href="README.he.md">🇮🇱 עברית</a> •
+  <a href="README.ar.md">🇸🇦 العربية</a> •
+  <a href="README.ru.md">🇷🇺 Русский</a> •
+  <a href="README.pl.md">🇵🇱 Polski</a> •
+  <a href="README.cs.md">🇨🇿 Čeština</a> •
+  <a href="README.nl.md">🇳🇱 Nederlands</a> •
+  <a href="README.tr.md">🇹🇷 Türkçe</a> •
+  <a href="README.uk.md">🇺🇦 Українська</a> •
+  <a href="README.vi.md">🇻🇳 Tiếng Việt</a> •
+  <a href="README.tl.md">🇵🇭 Tagalog</a> •
+  <a href="README.id.md">🇮🇩 Indonesia</a> •
+  <a href="README.th.md">🇹🇭 ไทย</a> •
+  <a href="README.hi.md">🇮🇳 हिन्दी</a> •
+  <a href="README.bn.md">🇧🇩 বাংলা</a> •
+  <a href="README.ur.md">🇵🇰 اردو</a> •
+  <a href="README.ro.md">🇷🇴 Română</a> •
+  <a href="README.sv.md">🇸🇪 Svenska</a> •
+  <a href="README.it.md">🇮🇹 Italiano</a> •
+  <a href="README.el.md">🇬🇷 Ελληνικά</a> •
+  <a href="README.hu.md">🇭🇺 Magyar</a> •
+  <a href="README.fi.md">🇫🇮 Suomi</a> •
+  <a href="README.da.md">🇩🇰 Dansk</a> •
+  <a href="README.no.md">🇳🇴 Norsk</a>
+</p>
+
+<h4 align="center">Sistema ng kompresyon ng persistent memory na ginawa para sa <a href="https://claude.com/claude-code" target="_blank">Claude Code</a>.</h4>
+
+<p align="center">
+  <a href="LICENSE">
+    <img src="https://img.shields.io/badge/License-AGPL%203.0-blue.svg" alt="License">
+  </a>
+  <a href="package.json">
+    <img src="https://img.shields.io/badge/version-6.5.0-green.svg" alt="Version">
+  </a>
+  <a href="package.json">
+    <img src="https://img.shields.io/badge/node-%3E%3D18.0.0-brightgreen.svg" alt="Node">
+  </a>
+  <a href="https://github.com/thedotmack/awesome-claude-code">
+    <img src="https://awesome.re/mentioned-badge.svg" alt="Mentioned in Awesome Claude Code">
+  </a>
+</p>
+
+<p align="center">
+  <a href="https://trendshift.io/repositories/15496" target="_blank">
+    <picture>
+      <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/thedotmack/claude-mem/main/docs/public/trendshift-badge-dark.svg">
+      <source media="(prefers-color-scheme: light)" srcset="https://raw.githubusercontent.com/thedotmack/claude-mem/main/docs/public/trendshift-badge.svg">
+      <img src="https://raw.githubusercontent.com/thedotmack/claude-mem/main/docs/public/trendshift-badge.svg" alt="thedotmack/claude-mem | Trendshift" width="250" height="55"/>
+    </picture>
+  </a>
+</p>
+
+<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>
+
+<p align="center">
+  <a href="#mabilis-na-pagsisimula">Mabilis na Pagsisimula</a> •
+  <a href="#paano-ito-gumagana">Paano Ito Gumagana</a> •
+  <a href="#mga-search-tool-ng-mcp">Mga Search Tool</a> •
+  <a href="#dokumentasyon">Dokumentasyon</a> •
+  <a href="#konpigurasyon">Konpigurasyon</a> •
+  <a href="#pag-troubleshoot">Pag-troubleshoot</a> •
+  <a href="#lisensya">Lisensya</a>
+</p>
+
+<p align="center">
+  Pinapanatili ng Claude-Mem ang konteksto sa pagitan ng mga session sa pamamagitan ng awtomatikong pagkuha ng mga obserbasyon sa paggamit ng mga tool, pagbuo ng mga semantikong buod, at paggawa nitong available sa mga susunod na session. Dahil dito, napapanatili ni Claude ang tuloy-tuloy na kaalaman tungkol sa mga proyekto kahit matapos o muling kumonekta ang mga session.
+</p>
+
+---
+
+## Mabilis na Pagsisimula
+
+Magsimula ng bagong Claude Code session sa terminal at ilagay ang mga sumusunod na command:
+
+```
+/plugin marketplace add thedotmack/claude-mem
+
+/plugin install claude-mem
+```
+
+I-restart ang Claude Code. Awtomatikong lalabas sa mga bagong session ang konteksto mula sa mga nakaraang session.
+
+**Mga Pangunahing Tampok:**
+
+- 🧠 **Persistent Memory** - Nananatili ang konteksto sa pagitan ng mga session
+- 📊 **Progressive Disclosure** - Layered na pagkuha ng memory na may visibility ng token cost
+- 🔍 **Skill-Based Search** - I-query ang history ng proyekto gamit ang mem-search skill
+- 🖥️ **Web Viewer UI** - Real-time memory stream sa http://localhost:37777
+- 💻 **Claude Desktop Skill** - Maghanap sa memory mula sa Claude Desktop conversations
+- 🔒 **Privacy Control** - Gamitin ang `<private>` tags para hindi ma-store ang sensitibong nilalaman
+- ⚙️ **Context Configuration** - Mas pinong kontrol kung anong konteksto ang ini-inject
+- 🤖 **Automatic Operation** - Walang kailangang manual na intervention
+- 🔗 **Citations** - I-refer ang mga lumang obserbasyon gamit ang IDs (i-access sa http://localhost:37777/api/observation/{id} o tingnan lahat sa web viewer sa http://localhost:37777)
+- 🧪 **Beta Channel** - Subukan ang mga experimental feature tulad ng Endless Mode sa pamamagitan ng version switching
+
+---
+
+## Dokumentasyon
+
+📚 **[Tingnan ang Buong Dokumentasyon](https://docs.claude-mem.ai/)** - I-browse sa opisyal na website
+
+### Pagsisimula
+
+- **[Gabay sa Pag-install](https://docs.claude-mem.ai/installation)** - Mabilis na pagsisimula at advanced installation
+- **[Gabay sa Paggamit](https://docs.claude-mem.ai/usage/getting-started)** - Paano awtomatikong gumagana ang Claude-Mem
+- **[Mga Search Tool](https://docs.claude-mem.ai/usage/search-tools)** - I-query ang history ng proyekto gamit ang natural language
+- **[Mga Beta Feature](https://docs.claude-mem.ai/beta-features)** - Subukan ang mga experimental feature tulad ng Endless Mode
+
+### Best Practices
+
+- **[Context Engineering](https://docs.claude-mem.ai/context-engineering)** - Mga prinsipyo ng context optimization para sa AI agents
+- **[Progressive Disclosure](https://docs.claude-mem.ai/progressive-disclosure)** - Pilosopiya sa likod ng context priming strategy ng Claude-Mem
+
+### Arkitektura
+
+- **[Overview](https://docs.claude-mem.ai/architecture/overview)** - Mga bahagi ng sistema at daloy ng data
+- **[Architecture Evolution](https://docs.claude-mem.ai/architecture-evolution)** - Ang paglalakbay mula v3 hanggang v5
+- **[Hooks Architecture](https://docs.claude-mem.ai/hooks-architecture)** - Paano gumagamit ang Claude-Mem ng lifecycle hooks
+- **[Hooks Reference](https://docs.claude-mem.ai/architecture/hooks)** - 7 hook scripts, ipinaliwanag
+- **[Worker Service](https://docs.claude-mem.ai/architecture/worker-service)** - HTTP API at Bun management
+- **[Database](https://docs.claude-mem.ai/architecture/database)** - SQLite schema at FTS5 search
+- **[Search Architecture](https://docs.claude-mem.ai/architecture/search-architecture)** - Hybrid search gamit ang Chroma vector database
+
+### Konpigurasyon at Pagbuo
+
+- **[Konpigurasyon](https://docs.claude-mem.ai/configuration)** - Environment variables at settings
+- **[Pagbuo](https://docs.claude-mem.ai/development)** - Build, test, at contribution workflow
+- **[Pag-troubleshoot](https://docs.claude-mem.ai/troubleshooting)** - Karaniwang isyu at solusyon
+
+---
+
+## Paano Ito Gumagana
+
+**Mga Pangunahing Bahagi:**
+
+1. **5 Lifecycle Hooks** - SessionStart, UserPromptSubmit, PostToolUse, Stop, SessionEnd (6 hook scripts)
+2. **Smart Install** - Cached dependency checker (pre-hook script, hindi lifecycle hook)
+3. **Worker Service** - HTTP API sa port 37777 na may web viewer UI at 10 search endpoints, pinamamahalaan ng Bun
+4. **SQLite Database** - Nag-iimbak ng sessions, observations, summaries
+5. **mem-search Skill** - Natural language queries na may progressive disclosure
+6. **Chroma Vector Database** - Hybrid semantic + keyword search para sa matalinong pagkuha ng konteksto
+
+Tingnan ang [Architecture Overview](https://docs.claude-mem.ai/architecture/overview) para sa detalye.
+
+---
+
+## Mga Search Tool ng MCP
+
+Nagbibigay ang Claude-Mem ng intelligent memory search sa pamamagitan ng **5 MCP tools** na sumusunod sa token-efficient na **3-layer workflow pattern**:
+
+**Ang 3-Layer Workflow:**
+
+1. **`search`** - Kumuha ng compact index na may IDs (~50-100 tokens/result)
+2. **`timeline`** - Kumuha ng chronological context sa paligid ng mga interesting na result
+3. **`get_observations`** - Kunin ang full details PARA LANG sa na-filter na IDs (~500-1,000 tokens/result)
+
+**Paano Ito Gumagana:**
+
+- Gumagamit si Claude ng MCP tools para maghanap sa iyong memory
+- Magsimula sa `search` para makakuha ng index ng results
+- Gamitin ang `timeline` para makita ang nangyari sa paligid ng mga partikular na observation
+- Gamitin ang `get_observations` para kunin ang full details ng mga relevant na IDs
+- Gamitin ang `save_memory` para manual na mag-store ng importanteng impormasyon
+- **~10x tipid sa tokens** dahil nagfi-filter muna bago kunin ang full details
+
+**Available na MCP Tools:**
+
+1. **`search`** - Hanapin ang memory index gamit ang full-text queries, may filters (type/date/project)
+2. **`timeline`** - Kumuha ng chronological context sa paligid ng isang observation o query
+3. **`get_observations`** - Kumuha ng full observation details gamit ang IDs (laging i-batch ang maraming IDs)
+4. **`save_memory`** - Manual na mag-save ng memory/observation para sa semantic search
+5. **`__IMPORTANT`** - Workflow documentation (laging visible kay Claude)
+
+**Halimbawa ng Paggamit:**
+
+```typescript
+// Step 1: Search for index
+search(query="authentication bug", type="bugfix", limit=10)
+
+// Step 2: Review index, identify relevant IDs (e.g., #123, #456)
+
+// 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")
+```
+
+Tingnan ang [Search Tools Guide](https://docs.claude-mem.ai/usage/search-tools) para sa mas detalyadong mga halimbawa.
+
+---
+
+## Mga Beta Feature
+
+May **beta channel** ang Claude-Mem na may mga experimental feature gaya ng **Endless Mode** (biomimetic memory architecture para sa mas mahahabang session). Magpalit sa pagitan ng stable at beta versions sa web viewer UI sa http://localhost:37777 → Settings.
+
+Tingnan ang **[Dokumentasyon ng Mga Beta Feature](https://docs.claude-mem.ai/beta-features)** para sa detalye ng Endless Mode at kung paano ito subukan.
+
+---
+
+## Mga Pangangailangan ng Sistema
+
+- **Node.js**: 18.0.0 o mas mataas
+- **Claude Code**: Pinakabagong bersyon na may plugin support
+- **Bun**: JavaScript runtime at process manager (auto-installed kung wala)
+- **uv**: Python package manager para sa vector search (auto-installed kung wala)
+- **SQLite 3**: Para sa persistent storage (kasama)
+
+---
+
+### Mga Tala sa Windows Setup
+
+Kung makakita ka ng error gaya ng:
+
+```powershell
+npm : The term 'npm' is not recognized as the name of a cmdlet
+```
+
+Siguraduhing naka-install ang Node.js at npm at nakadagdag sa PATH. I-download ang pinakabagong Node.js installer mula sa https://nodejs.org at i-restart ang terminal matapos mag-install.
+
+---
+
+## Konpigurasyon
+
+Pinamamahalaan ang settings sa `~/.claude-mem/settings.json` (auto-created na may defaults sa unang run). I-configure ang AI model, worker port, data directory, log level, at context injection settings.
+
+Tingnan ang **[Gabay sa Konpigurasyon](https://docs.claude-mem.ai/configuration)** para sa lahat ng available na settings at mga halimbawa.
+
+---
+
+## Pagbuo
+
+Tingnan ang **[Gabay nang pagbuo](https://docs.claude-mem.ai/development)** para sa pag build instructions, testing, at contribution workflow.
+
+---
+
+## Pag-troubleshoot
+
+Kung may issue, ilarawan ang problema kay Claude at awtomatikong magdi-diagnose at magbibigay ng mga ayos ang troubleshoot skill.
+
+Tingnan ang **[Troubleshooting Guide](https://docs.claude-mem.ai/troubleshooting)** para sa mga karaniwang isyu at solusyon.
+
+---
+
+## Bug Reports
+
+Gumawa ng kumpletong bug reports gamit ang automated generator:
+
+```bash
+cd ~/.claude/plugins/marketplaces/thedotmack
+npm run bug-report
+```
+
+## Pag-aambag
+
+Malugod na tinatanggap ang mga kontribusyon! Pakisunod:
+
+1. I-fork ang repository
+2. Gumawa ng feature branch
+3. Gawin ang mga pagbabago kasama ang tests
+4. I-update ang dokumentasyon
+5. Mag-submit ng Pull Request
+
+Tingnan ang [Gabay nang pagbuo](https://docs.claude-mem.ai/development) para sa contribution workflow.
+
+---
+
+## Lisensya
+
+Ang proyektong ito ay licensed sa ilalim ng **GNU Affero General Public License v3.0** (AGPL-3.0).
+
+Copyright (C) 2025 Alex Newman (@thedotmack). All rights reserved.
+
+Tingnan ang [LICENSE](LICENSE) file para sa buong detalye.
+
+**Ano ang ibig sabihin nito:**
+
+- Maaari mong gamitin, baguhin, at ipamahagi ang software na ito nang libre
+- Kung babaguhin mo at i-deploy sa isang network server, kailangan mong gawing available ang iyong source code
+- Dapat ding naka-license sa AGPL-3.0 ang mga derivative works
+- WALANG WARRANTY para sa software na ito
+
+**Tala tungkol sa Ragtime**: Ang `ragtime/` directory ay may hiwalay na lisensya sa ilalim ng **PolyForm Noncommercial License 1.0.0**. Tingnan ang [ragtime/LICENSE](ragtime/LICENSE) para sa detalye.
+
+---
+
+## Suporta
+
+- **Dokumentasyon**: [docs/](docs/)
+- **Issues**: [GitHub Issues](https://github.com/thedotmack/claude-mem/issues)
+- **Repository**: [github.com/thedotmack/claude-mem](https://github.com/thedotmack/claude-mem)
+- **Author**: Alex Newman ([@thedotmack](https://github.com/thedotmack))
+
+---
+
+**Built with Claude Agent SDK** | **Powered by Claude Code** | **Made with TypeScript**

docs/i18n/pt.md

@@ -0,0 +1,305 @@
+🌐 Esta é uma tradução manual por mig4ng. Correções da comunidade são bem-vindas!
+
+---
+<h1 align="center">
+  <br>
+  <a href="https://github.com/thedotmack/claude-mem">
+    <picture>
+      <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/thedotmack/claude-mem/main/docs/public/claude-mem-logo-for-dark-mode.webp">
+      <source media="(prefers-color-scheme: light)" srcset="https://raw.githubusercontent.com/thedotmack/claude-mem/main/docs/public/claude-mem-logo-for-light-mode.webp">
+      <img src="https://raw.githubusercontent.com/thedotmack/claude-mem/main/docs/public/claude-mem-logo-for-light-mode.webp" alt="Claude-Mem" width="400">
+    </picture>
+  </a>
+  <br>
+</h1>
+
+<p align="center">
+  <a href="README.zh.md">🇨🇳 中文</a> •
+  <a href="README.zh-tw.md">🇹🇼 繁體中文</a> •
+  <a href="README.ja.md">🇯🇵 日本語</a> •
+  <a href="README.pt.md">🇵🇹 Português</a> •
+  <a href="README.pt-br.md">🇧🇷 Português (Brasil)</a> •
+  <a href="README.ko.md">🇰🇷 한국어</a> •
+  <a href="README.es.md">🇪🇸 Español</a> •
+  <a href="README.de.md">🇩🇪 Deutsch</a> •
+  <a href="README.fr.md">🇫🇷 Français</a>
+  <a href="README.he.md">🇮🇱 עברית</a> •
+  <a href="README.ar.md">🇸🇦 العربية</a> •
+  <a href="README.ru.md">🇷🇺 Русский</a> •
+  <a href="README.pl.md">🇵🇱 Polski</a> •
+  <a href="README.cs.md">🇨🇿 Čeština</a> •
+  <a href="README.nl.md">🇳🇱 Nederlands</a> •
+  <a href="README.tr.md">🇹🇷 Türkçe</a> •
+  <a href="README.uk.md">🇺🇦 Українська</a> •
+  <a href="README.vi.md">🇻🇳 Tiếng Việt</a> •
+  <a href="README.id.md">🇮🇩 Indonesia</a> •
+  <a href="README.th.md">🇹🇭 ไทย</a> •
+  <a href="README.hi.md">🇮🇳 हिन्दी</a> •
+  <a href="README.bn.md">🇧🇩 বাংলা</a> •
+  <a href="README.ur.md">🇵🇰 اردو</a> •
+  <a href="README.ro.md">🇷🇴 Română</a> •
+  <a href="README.sv.md">🇸🇪 Svenska</a> •
+  <a href="README.it.md">🇮🇹 Italiano</a> •
+  <a href="README.el.md">🇬🇷 Ελληνικά</a> •
+  <a href="README.hu.md">🇭🇺 Magyar</a> •
+  <a href="README.fi.md">🇫🇮 Suomi</a> •
+  <a href="README.da.md">🇩🇰 Dansk</a> •
+  <a href="README.no.md">🇳🇴 Norsk</a>
+</p>
+
+<h4 align="center">Sistema de compressão de memória persistente construído para <a href="https://claude.com/claude-code" target="_blank">Claude Code</a>.</h4>
+
+<p align="center">
+  <a href="LICENSE">
+    <img src="https://img.shields.io/badge/License-AGPL%203.0-blue.svg" alt="License">
+  </a>
+  <a href="package.json">
+    <img src="https://img.shields.io/badge/version-6.5.0-green.svg" alt="Version">
+  </a>
+  <a href="package.json">
+    <img src="https://img.shields.io/badge/node-%3E%3D18.0.0-brightgreen.svg" alt="Node">
+  </a>
+  <a href="https://github.com/thedotmack/awesome-claude-code">
+    <img src="https://awesome.re/mentioned-badge.svg" alt="Mentioned in Awesome Claude Code">
+  </a>
+</p>
+
+<p align="center">
+  <a href="https://trendshift.io/repositories/15496" target="_blank">
+    <picture>
+      <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/thedotmack/claude-mem/main/docs/public/trendshift-badge-dark.svg">
+      <source media="(prefers-color-scheme: light)" srcset="https://raw.githubusercontent.com/thedotmack/claude-mem/main/docs/public/trendshift-badge.svg">
+      <img src="https://raw.githubusercontent.com/thedotmack/claude-mem/main/docs/public/trendshift-badge.svg" alt="thedotmack/claude-mem | Trendshift" width="250" height="55"/>
+    </picture>
+  </a>
+</p>
+
+<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>
+
+<p align="center">
+  <a href="#início-rápido">Início Rápido</a> •
+  <a href="#como-funciona">Como Funciona</a> •
+  <a href="#ferramentas-de-procura-mcp">Ferramentas de Procura</a> •
+  <a href="#documentação">Documentação</a> •
+  <a href="#configuração">Configuração</a> •
+  <a href="#solução-de-problemas">Solução de Problemas</a> •
+  <a href="#licença">Licença</a>
+</p>
+
+<p align="center">
+  Claude-Mem preserva o contexto perfeitamente entre sessões, capturando automaticamente observações de uso de ferramentas, gerando resumos semânticos e disponibilizando-os para sessões futuras. Isso permite que Claude mantenha a continuidade do conhecimento sobre projetos mesmo após o término ou reconexão de sessões.
+</p>
+
+---
+
+## Início Rápido
+
+Inicie uma nova sessão do Claude Code no terminal e digite os seguintes comandos:
+
+```
+> /plugin marketplace add thedotmack/claude-mem
+
+> /plugin install claude-mem
+```
+
+Reinicie o Claude Code. O contexto de sessões anteriores aparecerá automaticamente em novas sessões.
+
+**Principais Recursos:**
+
+- 🧠 **Memória Persistente** - O contexto sobrevive entre sessões
+- 📊 **Divulgação Progressiva** - Recuperação de memória em camadas com visibilidade de custo de tokens
+- 🔍 **Procura Baseada em Skill** - Consulte seu histórico de projeto com a skill mem-search
+- 🖥️ **Interface Web de Visualização** - Fluxo de memória em tempo real em http://localhost:37777
+- 💻 **Skill para Claude Desktop** - Busque memória em conversas do Claude Desktop
+- 🔒 **Controle de Privacidade** - Use tags `<private>` para excluir conteúdo sensível do armazenamento
+- ⚙️ **Configuração de Contexto** - Controle refinado sobre qual contexto é injetado
+- 🤖 **Operação Automática** - Nenhuma intervenção manual necessária
+- 🔗 **Citações** - Referencie observações passadas com IDs (acesse via http://localhost:37777/api/observation/{id} ou visualize todas no visualizador web em http://localhost:37777)
+- 🧪 **Canal Beta** - Experimente recursos experimentais como o Endless Mode através da troca de versões
+
+---
+
+## Documentação
+
+📚 **[Ver Documentação Completa](https://docs.claude-mem.ai/)** - Navegar no site oficial
+
+### Começando
+
+- **[Guia de Instalação](https://docs.claude-mem.ai/installation)** - Início rápido e instalação avançada
+- **[Guia de Uso](https://docs.claude-mem.ai/usage/getting-started)** - Como Claude-Mem funciona automaticamente
+- **[Ferramentas de Procura](https://docs.claude-mem.ai/usage/search-tools)** - Consulte seu histórico de projeto com linguagem natural
+- **[Recursos Beta](https://docs.claude-mem.ai/beta-features)** - Experimente recursos experimentais como o Endless Mode
+
+### Melhores Práticas
+
+- **[Engenharia de Contexto](https://docs.claude-mem.ai/context-engineering)** - Princípios de otimização de contexto para agentes de IA
+- **[Divulgação Progressiva](https://docs.claude-mem.ai/progressive-disclosure)** - Filosofia por trás da estratégia de preparação de contexto do Claude-Mem
+
+### Arquitetura
+
+- **[Visão Geral](https://docs.claude-mem.ai/architecture/overview)** - Componentes do sistema e fluxo de dados
+- **[Evolução da Arquitetura](https://docs.claude-mem.ai/architecture-evolution)** - A jornada da v3 à v5
+- **[Arquitetura de Hooks](https://docs.claude-mem.ai/hooks-architecture)** - Como Claude-Mem usa hooks de ciclo de vida
+- **[Referência de Hooks](https://docs.claude-mem.ai/architecture/hooks)** - 7 scripts de hook explicados
+- **[Serviço Worker](https://docs.claude-mem.ai/architecture/worker-service)** - API HTTP e gerenciamento do Bun
+- **[Banco de Dados](https://docs.claude-mem.ai/architecture/database)** - Schema SQLite e Procura FTS5
+- **[Arquitetura de Procura](https://docs.claude-mem.ai/architecture/search-architecture)** - Procura híbrida com banco de dados vetorial Chroma
+
+### Configuração e Desenvolvimento
+
+- **[Configuração](https://docs.claude-mem.ai/configuration)** - Variáveis de ambiente e configurações
+- **[Desenvolvimento](https://docs.claude-mem.ai/development)** - Build, testes e contribuição
+- **[Solução de Problemas](https://docs.claude-mem.ai/troubleshooting)** - Problemas comuns e soluções
+
+---
+
+## Como Funciona
+
+**Componentes Principais:**
+
+1. **5 Hooks de Ciclo de Vida** - SessionStart, UserPromptSubmit, PostToolUse, Stop, SessionEnd (6 scripts de hook)
+2. **Instalação Inteligente** - Verificador de dependências em cache (script pré-hook, não um hook de ciclo de vida)
+3. **Serviço Worker** - API HTTP na porta 37777 com interface de visualização web e 10 endpoints de Procura, gerenciado pelo Bun
+4. **Banco de Dados SQLite** - Armazena sessões, observações, resumos
+5. **Skill mem-search** - Consultas em linguagem natural com divulgação progressiva
+6. **Banco de Dados Vetorial Chroma** - Procura híbrida semântica + palavra-chave para recuperação inteligente de contexto
+
+Veja [Visão Geral da Arquitetura](https://docs.claude-mem.ai/architecture/overview) para detalhes.
+
+---
+
+## Skill mem-search
+
+Claude-Mem fornece Procura inteligente através da skill mem-search que se auto-invoca quando você pergunta sobre trabalhos anteriores:
+
+**Como Funciona:**
+- Pergunte naturalmente: *"O que fizemos na última sessão?"* ou *"Já corrigimos esse bug antes?"*
+- Claude invoca automaticamente a skill mem-search para encontrar contexto relevante
+
+**Operações de Procura Disponíveis:**
+
+1. **Search Observations** - Procura de texto completo em observações
+2. **Search Sessions** - Procura de texto completo em resumos de sessão
+3. **Search Prompts** - Procura em solicitações brutas do usuário
+4. **By Concept** - Encontre por tags de conceito (discovery, problem-solution, pattern, etc.)
+5. **By File** - Encontre observações que referenciam arquivos específicos
+6. **By Type** - Encontre por tipo (decision, bugfix, feature, refactor, discovery, change)
+7. **Recent Context** - Obtenha contexto de sessão recente para um projeto
+8. **Timeline** - Obtenha linha do tempo unificada de contexto em torno de um ponto específico no tempo
+9. **Timeline by Query** - Busque observações e obtenha contexto de linha do tempo em torno da melhor correspondência
+10. **API Help** - Obtenha documentação da API de Procura
+
+**Exemplos de Consultas em Linguagem Natural:**
+
+```
+"Quais bugs corrigimos na última sessão?"
+"Como implementamos a autenticação?"
+"Quais mudanças foram feitas em worker-service.ts?"
+"Mostre-me trabalhos recentes neste projeto"
+"O que estava acontecendo quando adicionamos a interface de visualização?"
+```
+
+Veja [Guia de Ferramentas de Procura](https://docs.claude-mem.ai/usage/search-tools) para exemplos detalhados.
+
+---
+
+## Recursos Beta
+
+Claude-Mem oferece um **canal beta** com recursos experimentais como **Endless Mode** (arquitetura de memória biomimética para sessões estendidas). Alterne entre versões estável e beta pela interface de visualização web em http://localhost:37777 → Settings.
+
+Veja **[Documentação de Recursos Beta](https://docs.claude-mem.ai/beta-features)** para detalhes sobre o Endless Mode e como experimentá-lo.
+
+---
+
+## Requisitos do Sistema
+
+- **Node.js**: 18.0.0 ou superior
+- **Claude Code**: Versão mais recente com suporte a plugins
+- **Bun**: Runtime JavaScript e gerenciador de processos (instalado automaticamente se ausente)
+- **uv**: Gerenciador de pacotes Python para Procura vetorial (instalado automaticamente se ausente)
+- **SQLite 3**: Para armazenamento persistente (incluído)
+
+---
+
+## Configuração
+
+As configurações são gerenciadas em `~/.claude-mem/settings.json` (criado automaticamente com valores padrão na primeira execução). Configure modelo de IA, porta do worker, diretório de dados, nível de log e configurações de injeção de contexto.
+
+Veja o **[Guia de Configuração](https://docs.claude-mem.ai/configuration)** para todas as configurações disponíveis e exemplos.
+
+---
+
+## Desenvolvimento
+
+Veja o **[Guia de Desenvolvimento](https://docs.claude-mem.ai/development)** para instruções de build, testes e fluxo de contribuição.
+
+---
+
+## Solução de Problemas
+
+Se você estiver enfrentando problemas, descreva o problema para Claude e a skill troubleshoot diagnosticará automaticamente e fornecerá correções.
+
+Veja o **[Guia de Solução de Problemas](https://docs.claude-mem.ai/troubleshooting)** para problemas comuns e soluções.
+
+---
+
+## Relatos de Bug
+
+Crie relatos de bug abrangentes com o gerador automatizado:
+
+```bash
+cd ~/.claude/plugins/marketplaces/thedotmack
+npm run bug-report
+```
+
+## Contribuindo
+
+Contribuições são bem-vindas! Por favor:
+
+1. Faça um fork do repositório
+2. Crie uma branch de feature
+3. Faça suas alterações com testes
+4. Atualize a documentação
+5. Envie um Pull Request
+
+Veja [Guia de Desenvolvimento](https://docs.claude-mem.ai/development) para o fluxo de contribuição.
+
+---
+
+## Licença
+
+Este projeto está licenciado sob a **GNU Affero General Public License v3.0** (AGPL-3.0).
+
+Copyright (C) 2025 Alex Newman (@thedotmack). Todos os direitos reservados.
+
+Veja o arquivo [LICENSE](LICENSE) para detalhes completos.
+
+**O Que Isso Significa:**
+
+- Você pode usar, modificar e distribuir este software livremente
+- Se você modificar e implantar em um servidor de rede, você deve disponibilizar seu código-fonte
+- Trabalhos derivados também devem ser licenciados sob AGPL-3.0
+- NÃO HÁ GARANTIA para este software
+
+**Nota sobre Ragtime**: O diretório `ragtime/` é licenciado separadamente sob a **PolyForm Noncommercial License 1.0.0**. Veja [ragtime/LICENSE](ragtime/LICENSE) para detalhes.
+
+---
+
+## Suporte
+
+- **Documentação**: [docs/](docs/)
+- **Issues**: [GitHub Issues](https://github.com/thedotmack/claude-mem/issues)
+- **Repositório**: [github.com/thedotmack/claude-mem](https://github.com/thedotmack/claude-mem)
+- **Autor**: Alex Newman ([@thedotmack](https://github.com/thedotmack))
+
+---
+
+**Construído com Claude Agent SDK** | **Desenvolvido por Claude Code** | **Feito com TypeScript** | **Editado por mig4ng**

docs/public/docs.json

@@ -62,7 +62,8 @@
         "icon": "lightbulb",
         "pages": [
           "context-engineering",
-          "progressive-disclosure"
+          "progressive-disclosure",
+          "smart-explore-benchmark"
         ]
       },
       {
@@ -73,7 +74,8 @@
           "modes",
           "development",
           "troubleshooting",
-          "platform-integration"
+          "platform-integration",
+          "openclaw-integration"
         ]
       },
       {

docs/public/installation.mdx

@@ -22,6 +22,10 @@ That's it! The plugin will automatically:
 
 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.
+
 ## System Requirements
 
 - **Node.js**: 18.0.0 or higher

docs/public/openclaw-integration.mdx

@@ -0,0 +1,385 @@
+---
+title: OpenClaw Integration
+description: Persistent memory for OpenClaw agents — observation recording, MEMORY.md live sync, and real-time observation feeds
+icon: dragon
+---
+
+## Overview
+
+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
+3. **Observation feed** — Streams new observations to messaging channels (Telegram, Discord, Slack, etc.) in real-time via SSE
+
+<Info>
+OpenClaw's embedded runner (`pi-embedded`) calls the Anthropic API directly without spawning a `claude` process, so claude-mem's standard hooks never fire. This plugin bridges that gap by using OpenClaw's event system to capture the same data.
+</Info>
+
+## How It Works
+
+```plaintext
+OpenClaw Gateway
+  │
+  ├── before_agent_start ──→ Sync MEMORY.md + Init session
+  ├── tool_result_persist ──→ Record observation + Re-sync MEMORY.md
+  ├── agent_end ────────────→ Summarize + Complete session
+  └── gateway_start ────────→ Reset session tracking
+                    │
+                    ▼
+         Claude-Mem Worker (localhost:37777)
+           ├── POST /api/sessions/init
+           ├── POST /api/sessions/observations
+           ├── POST /api/sessions/summarize
+           ├── POST /api/sessions/complete
+           ├── GET  /api/context/inject ──→ MEMORY.md content
+           └── GET  /stream ─────────────→ SSE → Messaging channels
+```
+
+### Event Lifecycle
+
+<Steps>
+  <Step title="Agent starts (before_agent_start)">
+    When an OpenClaw agent starts, the plugin does two things:
+
+    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.
+  </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.
+
+    Tools prefixed with `memory_` are skipped to avoid recursive recording.
+  </Step>
+  <Step title="Agent finishes (agent_end)">
+    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.
+  </Step>
+</Steps>
+
+### MEMORY.md Live Sync
+
+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:
+
+- 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.
+
+<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.
+</Info>
+
+### Observation Feed (SSE → Messaging)
+
+The plugin runs a background service that connects to the worker's SSE stream (`GET /stream`) and forwards `new_observation` events to a configured messaging channel. This lets you monitor what your agents are learning in real-time from Telegram, Discord, Slack, or any supported OpenClaw channel.
+
+The SSE connection uses exponential backoff (1s → 30s) for automatic reconnection.
+
+## Setting Up the Observation Feed
+
+The observation feed sends a formatted message to your OpenClaw channel every time claude-mem creates a new observation. Each message includes the observation title and subtitle so you can follow along as your agents work.
+
+Messages look like this in your channel:
+
+```
+🧠 Claude-Mem Observation
+**Implemented retry logic for API client**
+Added exponential backoff with configurable max retries to handle transient failures
+```
+
+### Step 1: Choose your channel
+
+The observation feed works with any channel that your OpenClaw gateway has configured. You need two pieces of information:
+
+- **Channel type** — The name of the channel plugin registered with OpenClaw (e.g., `telegram`, `discord`, `slack`, `signal`, `whatsapp`, `line`)
+- **Target ID** — The chat ID, channel ID, or user ID where messages should be sent
+
+<AccordionGroup>
+  <Accordion title="Telegram" icon="telegram">
+    **Channel type:** `telegram`
+
+    **Target ID:** Your Telegram chat ID (numeric). To find it:
+    1. Message [@userinfobot](https://t.me/userinfobot) on Telegram
+    2. It will reply with your chat ID (e.g., `123456789`)
+    3. For group chats, the ID is negative (e.g., `-1001234567890`)
+
+    ```json
+    "observationFeed": {
+      "enabled": true,
+      "channel": "telegram",
+      "to": "123456789"
+    }
+    ```
+  </Accordion>
+
+  <Accordion title="Discord" icon="discord">
+    **Channel type:** `discord`
+
+    **Target ID:** The Discord channel ID. To find it:
+    1. Enable Developer Mode in Discord (Settings → Advanced → Developer Mode)
+    2. Right-click the channel → Copy Channel ID
+
+    ```json
+    "observationFeed": {
+      "enabled": true,
+      "channel": "discord",
+      "to": "1234567890123456789"
+    }
+    ```
+  </Accordion>
+
+  <Accordion title="Slack" icon="slack">
+    **Channel type:** `slack`
+
+    **Target ID:** The Slack channel ID (not the channel name). To find it:
+    1. Open the channel in Slack
+    2. Click the channel name at the top
+    3. Scroll to the bottom of the channel details — the ID looks like `C01ABC2DEFG`
+
+    ```json
+    "observationFeed": {
+      "enabled": true,
+      "channel": "slack",
+      "to": "C01ABC2DEFG"
+    }
+    ```
+  </Accordion>
+
+  <Accordion title="Signal" icon="signal-messenger">
+    **Channel type:** `signal`
+
+    **Target ID:** The Signal phone number or group ID configured in your OpenClaw gateway.
+
+    ```json
+    "observationFeed": {
+      "enabled": true,
+      "channel": "signal",
+      "to": "+1234567890"
+    }
+    ```
+  </Accordion>
+
+  <Accordion title="WhatsApp" icon="whatsapp">
+    **Channel type:** `whatsapp`
+
+    **Target ID:** The WhatsApp phone number or group JID configured in your OpenClaw gateway.
+
+    ```json
+    "observationFeed": {
+      "enabled": true,
+      "channel": "whatsapp",
+      "to": "+1234567890"
+    }
+    ```
+  </Accordion>
+
+  <Accordion title="LINE" icon="line">
+    **Channel type:** `line`
+
+    **Target ID:** The LINE user ID or group ID from the LINE Developer Console.
+
+    ```json
+    "observationFeed": {
+      "enabled": true,
+      "channel": "line",
+      "to": "U1234567890abcdef"
+    }
+    ```
+  </Accordion>
+</AccordionGroup>
+
+### Step 2: Add the config to your gateway
+
+Add the `observationFeed` block to your claude-mem plugin config in your OpenClaw gateway configuration:
+
+```json
+{
+  "plugins": {
+    "claude-mem": {
+      "enabled": true,
+      "config": {
+        "project": "my-project",
+        "observationFeed": {
+          "enabled": true,
+          "channel": "telegram",
+          "to": "123456789"
+        }
+      }
+    }
+  }
+}
+```
+
+<Warning>
+The `channel` value must match a channel plugin that is already configured and running on your OpenClaw gateway. If the channel isn't registered, you'll see `Unknown channel type: <channel>` in the logs.
+</Warning>
+
+### Step 3: Verify the connection
+
+After starting the gateway, check that the feed is connected:
+
+1. **Check the logs** — You should see:
+   ```
+   [claude-mem] Observation feed starting — channel: telegram, target: 123456789
+   [claude-mem] Connecting to SSE stream at http://localhost:37777/stream
+   [claude-mem] Connected to SSE stream
+   ```
+
+2. **Use the status command** — Run `/claude_mem_feed` in any OpenClaw chat to see:
+   ```
+   Claude-Mem Observation Feed
+   Enabled: yes
+   Channel: telegram
+   Target: 123456789
+   Connection: connected
+   ```
+
+3. **Trigger a test** — Have an agent do some work. When the worker processes the tool usage into an observation, you'll receive a message in your configured channel.
+
+<Info>
+The feed only sends `new_observation` events — not raw tool usage. Observations are generated asynchronously by the worker's AI agent, so there's a 1-2 second delay between tool use and the observation message appearing in your channel.
+</Info>
+
+### Troubleshooting the Feed
+
+| Symptom | Cause | Fix |
+|---------|-------|-----|
+| `Connection: disconnected` | Worker not running or wrong port | Check `workerPort` config, run `npm run worker:status` |
+| `Connection: reconnecting` | Worker was running but connection dropped | The plugin auto-reconnects with backoff — wait up to 30s |
+| `Unknown channel type` in logs | Channel plugin not loaded on gateway | Verify your OpenClaw gateway has the channel plugin configured |
+| No messages appearing | Feed connected but no observations being created | Check that agents are running and the worker is processing observations |
+| `Observation feed disabled` in logs | `enabled` is `false` or missing | Set `observationFeed.enabled` to `true` |
+| `Observation feed misconfigured` in logs | Missing `channel` or `to` | Both `channel` and `to` are required |
+
+## Installation
+
+Run this one-liner to install everything automatically:
+
+```bash
+curl -fsSL https://install.cmem.ai/openclaw.sh | bash
+```
+
+The installer handles dependency checks (Bun, uv), plugin installation, memory slot configuration, AI provider setup, worker startup, and optional observation feed configuration.
+
+You can also pre-select options:
+
+```bash
+# With a specific AI provider
+curl -fsSL https://install.cmem.ai/openclaw.sh | bash -s -- --provider=gemini --api-key=YOUR_KEY
+
+# Fully unattended (defaults to Claude Max Plan)
+curl -fsSL https://install.cmem.ai/openclaw.sh | bash -s -- --non-interactive
+
+# Upgrade existing installation
+curl -fsSL https://install.cmem.ai/openclaw.sh | bash -s -- --upgrade
+```
+
+### Manual Configuration
+
+Add `claude-mem` to your OpenClaw gateway's plugin configuration:
+
+```json
+{
+  "plugins": {
+    "claude-mem": {
+      "enabled": true,
+      "config": {
+        "project": "my-project",
+        "syncMemoryFile": true,
+        "workerPort": 37777,
+        "observationFeed": {
+          "enabled": true,
+          "channel": "telegram",
+          "to": "your-chat-id"
+        }
+      }
+    }
+  }
+}
+```
+
+<Note>
+The claude-mem worker service must be running on the same machine as the OpenClaw gateway. The plugin communicates with it via HTTP on `localhost:37777`.
+</Note>
+
+## Configuration
+
+<ParamField body="project" type="string" default="openclaw">
+  Project name for scoping observations in the memory database. All observations from this gateway will be stored under this project name.
+</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.
+</ParamField>
+
+<ParamField body="workerPort" type="number" default={37777}>
+  Port for the claude-mem worker service. Override if your worker runs on a non-default port.
+</ParamField>
+
+<ParamField body="observationFeed.enabled" type="boolean" default={false}>
+  Enable live observation streaming to messaging channels.
+</ParamField>
+
+<ParamField body="observationFeed.channel" type="string">
+  Channel type: `telegram`, `discord`, `signal`, `slack`, `whatsapp`, `line`
+</ParamField>
+
+<ParamField body="observationFeed.to" type="string">
+  Target chat/user/channel ID to send observations to.
+</ParamField>
+
+## Commands
+
+### /claude_mem_feed
+
+Show or toggle the observation feed status.
+
+```
+/claude_mem_feed        # Show current status
+/claude_mem_feed on     # Request enable
+/claude_mem_feed off    # Request disable
+```
+
+### /claude_mem_status
+
+Check worker health and session status.
+
+```
+/claude_mem_status
+```
+
+Returns worker status, port, active session count, and observation feed connection state.
+
+## Architecture
+
+The plugin uses HTTP calls to the already-running claude-mem worker service rather than spawning subprocesses. This means:
+
+- No `bun` dependency required on the gateway
+- No process spawn overhead per event
+- Uses the same worker API that Claude Code hooks use
+- All operations are non-blocking (fire-and-forget where possible)
+
+### Session Tracking
+
+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`
+
+Both maps are cleared on `gateway_start`.
+
+## Requirements
+
+- Claude-mem worker service running on `localhost:37777` (or configured port)
+- OpenClaw gateway with plugin support
+- Network access between gateway and worker (localhost only)

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

@@ -0,0 +1,2 @@
+.vercel
+public/openclaw.sh

install/public/install.sh

@@ -0,0 +1,59 @@
+#!/bin/bash
+set -euo pipefail
+
+# claude-mem installer bootstrap
+# Usage: curl -fsSL https://install.cmem.ai | bash
+#   or:  curl -fsSL https://install.cmem.ai | bash -s -- --provider=gemini --api-key=YOUR_KEY
+
+INSTALLER_URL="https://install.cmem.ai/installer.js"
+
+# Colors
+RED='\033[0;31m'
+GREEN='\033[0;32m'
+CYAN='\033[0;36m'
+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

install/vercel.json

@@ -0,0 +1,22 @@
+{
+  "$schema": "https://openapi.vercel.sh/vercel.json",
+  "rewrites": [
+    { "source": "/", "destination": "/install.sh" }
+  ],
+  "headers": [
+    {
+      "source": "/(.*)\\.sh",
+      "headers": [
+        { "key": "Content-Type", "value": "text/plain; charset=utf-8" },
+        { "key": "Cache-Control", "value": "public, max-age=300, s-maxage=60" }
+      ]
+    },
+    {
+      "source": "/(.*)\\.js",
+      "headers": [
+        { "key": "Content-Type", "value": "application/javascript; charset=utf-8" },
+        { "key": "Cache-Control", "value": "public, max-age=300, s-maxage=60" }
+      ]
+    }
+  ]
+}

installer/build.mjs

@@ -0,0 +1,16 @@
+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

@@ -0,0 +1,21 @@
+{
+  "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

@@ -0,0 +1,49 @@
+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

@@ -0,0 +1,56 @@
+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

@@ -0,0 +1,168 @@
+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

@@ -0,0 +1,32 @@
+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

@@ -0,0 +1,167 @@
+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

@@ -0,0 +1,140 @@
+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

@@ -0,0 +1,174 @@
+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

@@ -0,0 +1,43 @@
+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

@@ -0,0 +1,67 @@
+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

@@ -0,0 +1,74 @@
+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

@@ -0,0 +1,82 @@
+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

@@ -0,0 +1,49 @@
+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

@@ -0,0 +1,17 @@
+{
+  "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/.gitignore

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

openclaw/Dockerfile.e2e

@@ -0,0 +1,69 @@
+# Dockerfile.e2e — End-to-end test: install claude-mem plugin on a real OpenClaw instance
+# Simulates the complete plugin installation flow a user would follow.
+#
+# Usage:
+#   docker build -f Dockerfile.e2e -t openclaw-e2e-test . && docker run --rm openclaw-e2e-test
+#
+# Interactive (for human testing):
+#   docker run --rm -it openclaw-e2e-test /bin/bash
+
+FROM ghcr.io/openclaw/openclaw:main
+
+USER root
+
+# Install curl for health checks in e2e-verify.sh, and TypeScript for building
+RUN apt-get update && apt-get install -y --no-install-recommends curl && rm -rf /var/lib/apt/lists/*
+RUN npm install -g typescript@5
+
+# Create staging directory for the plugin source
+WORKDIR /tmp/claude-mem-plugin
+
+# Copy plugin source files
+COPY package.json tsconfig.json openclaw.plugin.json ./
+COPY src/ ./src/
+
+# Build the plugin (TypeScript → JavaScript)
+# NODE_ENV=production is set in the base image; override to install devDependencies
+RUN NODE_ENV=development npm install && npx tsc
+
+# Create the installable plugin package:
+# OpenClaw `plugins install` expects package.json with openclaw.extensions field.
+# The package name must match the plugin ID in openclaw.plugin.json (claude-mem).
+# Only include the main plugin entry point, not test/mock files.
+RUN mkdir -p /tmp/claude-mem-installable/dist && \
+    cp dist/index.js /tmp/claude-mem-installable/dist/ && \
+    cp dist/index.d.ts /tmp/claude-mem-installable/dist/ 2>/dev/null || true && \
+    cp openclaw.plugin.json /tmp/claude-mem-installable/ && \
+    node -e " \
+      const pkg = { \
+        name: 'claude-mem', \
+        version: '1.0.0', \
+        type: 'module', \
+        main: 'dist/index.js', \
+        openclaw: { extensions: ['./dist/index.js'] } \
+      }; \
+      require('fs').writeFileSync('/tmp/claude-mem-installable/package.json', JSON.stringify(pkg, null, 2)); \
+    "
+
+# Switch back to app directory and node user for installation
+WORKDIR /app
+USER node
+
+# Create the OpenClaw config directory
+RUN mkdir -p /home/node/.openclaw
+
+# Install the plugin using OpenClaw's official CLI
+RUN node openclaw.mjs plugins install /tmp/claude-mem-installable
+
+# Enable the plugin
+RUN node openclaw.mjs plugins enable claude-mem
+
+# Copy the e2e verification script and mock worker
+COPY --chown=node:node e2e-verify.sh /app/e2e-verify.sh
+USER root
+RUN chmod +x /app/e2e-verify.sh && \
+    cp /tmp/claude-mem-plugin/dist/mock-worker.js /app/mock-worker.js
+USER node
+
+# Default: run the automated verification
+CMD ["/bin/bash", "/app/e2e-verify.sh"]

openclaw/SKILL.md

@@ -0,0 +1,458 @@
+# 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.
+
+## Quick Install (Recommended)
+
+Run this one-liner to install everything automatically:
+
+```bash
+curl -fsSL https://install.cmem.ai/openclaw.sh | bash
+```
+
+The installer handles dependency checks (Bun, uv), plugin installation, memory slot configuration, AI provider setup, worker startup, and optional observation feed configuration — all interactively.
+
+### Install with options
+
+Pre-select your AI provider and API key to skip interactive prompts:
+
+```bash
+curl -fsSL https://install.cmem.ai/openclaw.sh | bash -s -- --provider=gemini --api-key=YOUR_KEY
+```
+
+For fully unattended installation (defaults to Claude Max Plan, skips observation feed):
+
+```bash
+curl -fsSL https://install.cmem.ai/openclaw.sh | bash -s -- --non-interactive
+```
+
+To upgrade an existing installation (preserves settings, updates plugin):
+
+```bash
+curl -fsSL https://install.cmem.ai/openclaw.sh | bash -s -- --upgrade
+```
+
+After installation, skip to [Step 4: Restart the Gateway and Verify](#step-4-restart-the-gateway-and-verify) to confirm everything is working.
+
+---
+
+## Manual Setup
+
+The steps below are for manual installation if you prefer not to use the automated installer, or need to troubleshoot individual steps.
+
+### Step 1: Clone the Claude-Mem Repo
+
+First, clone the claude-mem repository to a location accessible by your OpenClaw gateway. This gives you the worker service source and the plugin code.
+
+```bash
+cd /opt  # or wherever you want to keep it
+git clone https://github.com/thedotmack/claude-mem.git
+cd claude-mem
+npm install
+npm run build
+```
+
+You'll need **bun** installed for the worker service. If you don't have it:
+
+```bash
+curl -fsSL https://bun.sh/install | bash
+```
+
+### Step 2: Get the Worker Running
+
+The claude-mem worker is an HTTP service on port 37777. It stores observations, generates summaries, and serves the context timeline. The plugin talks to it over HTTP — it doesn't matter where the worker is running, just that it's reachable on localhost:37777.
+
+#### Check if it's already running
+
+If this machine also runs Claude Code with claude-mem installed, the worker may already be running:
+
+```bash
+curl http://localhost:37777/api/health
+```
+
+**Got `{"status":"ok"}`?** The worker is already running. Skip to Step 3.
+
+**Got connection refused or no response?** The worker isn't running. Continue below.
+
+#### If Claude Code has claude-mem installed
+
+If claude-mem is installed as a Claude Code plugin (at `~/.claude/plugins/marketplaces/thedotmack/`), start the worker from that installation:
+
+```bash
+cd ~/.claude/plugins/marketplaces/thedotmack
+npm run worker:restart
+```
+
+Verify:
+```bash
+curl http://localhost:37777/api/health
+```
+
+**Got `{"status":"ok"}`?** You're set. Skip to Step 3.
+
+**Still not working?** Check `npm run worker:status` for error details, or check that bun is installed and on your PATH.
+
+#### If there's no Claude Code installation
+
+Run the worker from the cloned repo:
+
+```bash
+cd /opt/claude-mem  # wherever you cloned it
+npm run worker:start
+```
+
+Verify:
+```bash
+curl http://localhost:37777/api/health
+```
+
+**Got `{"status":"ok"}`?** You're set. Move to Step 3.
+
+**Still not working?** Debug steps:
+- Check that bun is installed: `bun --version`
+- Check the worker status: `npm run worker:status`
+- Check if something else is using port 37777: `lsof -i :37777`
+- Check logs: `npm run worker:logs` (if available)
+- Try running it directly to see errors: `bun plugin/scripts/worker-service.cjs start`
+
+### Step 3: Add the Plugin to Your Gateway
+
+Add the `claude-mem` plugin to your OpenClaw gateway configuration:
+
+```json
+{
+  "plugins": {
+    "claude-mem": {
+      "enabled": true,
+      "config": {
+        "project": "my-project",
+        "syncMemoryFile": true,
+        "workerPort": 37777
+      }
+    }
+  }
+}
+```
+
+#### Config fields explained
+
+- **`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.
+
+- **`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.
+
+---
+
+## Step 4: Restart the Gateway and Verify
+
+Restart your OpenClaw gateway so it picks up the new plugin configuration. After restart, check the gateway logs for:
+
+```
+[claude-mem] OpenClaw plugin loaded — v1.0.0 (worker: 127.0.0.1:37777)
+```
+
+If you see this, the plugin is loaded. You can also verify by running `/claude_mem_status` in any OpenClaw chat:
+
+```
+Claude-Mem Worker Status
+Status: ok
+Port: 37777
+Active sessions: 0
+Observation feed: disconnected
+```
+
+The observation feed shows `disconnected` because we haven't configured it yet. That's next.
+
+## Step 5: Verify Observations Are Being Recorded
+
+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
+
+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.
+
+You can also check the worker's viewer UI at http://localhost:37777 to see observations appearing in real time.
+
+## Step 6: Set Up the Observation Feed (Streaming to a Channel)
+
+The observation feed connects to the claude-mem worker's SSE (Server-Sent Events) stream and forwards every new observation to a messaging channel in real time. Your agents learn things, and you see them learning in your Telegram/Discord/Slack/etc.
+
+### What you'll see
+
+Every time claude-mem creates a new observation from your agent's tool usage, a message like this appears in your channel:
+
+```
+🧠 Claude-Mem Observation
+**Implemented retry logic for API client**
+Added exponential backoff with configurable max retries to handle transient failures
+```
+
+### Pick your channel
+
+You need two things:
+- **Channel type** — Must match a channel plugin already running on your OpenClaw gateway
+- **Target ID** — The chat/channel/user ID where messages go
+
+#### Telegram
+
+Channel type: `telegram`
+
+To find your chat ID:
+1. Message @userinfobot on Telegram — https://t.me/userinfobot
+2. It replies with your numeric chat ID (e.g., `123456789`)
+3. For group chats, the ID is negative (e.g., `-1001234567890`)
+
+```json
+"observationFeed": {
+  "enabled": true,
+  "channel": "telegram",
+  "to": "123456789"
+}
+```
+
+#### Discord
+
+Channel type: `discord`
+
+To find your channel ID:
+1. Enable Developer Mode in Discord: Settings → Advanced → Developer Mode
+2. Right-click the target channel → Copy Channel ID
+
+```json
+"observationFeed": {
+  "enabled": true,
+  "channel": "discord",
+  "to": "1234567890123456789"
+}
+```
+
+#### Slack
+
+Channel type: `slack`
+
+To find your channel ID (not the channel name):
+1. Open the channel in Slack
+2. Click the channel name at the top
+3. Scroll to the bottom of the channel details — the ID looks like `C01ABC2DEFG`
+
+```json
+"observationFeed": {
+  "enabled": true,
+  "channel": "slack",
+  "to": "C01ABC2DEFG"
+}
+```
+
+#### Signal
+
+Channel type: `signal`
+
+Use the phone number or group ID configured in your OpenClaw gateway's Signal plugin.
+
+```json
+"observationFeed": {
+  "enabled": true,
+  "channel": "signal",
+  "to": "+1234567890"
+}
+```
+
+#### WhatsApp
+
+Channel type: `whatsapp`
+
+Use the phone number or group JID configured in your OpenClaw gateway's WhatsApp plugin.
+
+```json
+"observationFeed": {
+  "enabled": true,
+  "channel": "whatsapp",
+  "to": "+1234567890"
+}
+```
+
+#### LINE
+
+Channel type: `line`
+
+Use the user ID or group ID from the LINE Developer Console.
+
+```json
+"observationFeed": {
+  "enabled": true,
+  "channel": "line",
+  "to": "U1234567890abcdef"
+}
+```
+
+### Add it to your config
+
+Your complete plugin config should now look like this (using Telegram as an example):
+
+```json
+{
+  "plugins": {
+    "claude-mem": {
+      "enabled": true,
+      "config": {
+        "project": "my-project",
+        "syncMemoryFile": true,
+        "workerPort": 37777,
+        "observationFeed": {
+          "enabled": true,
+          "channel": "telegram",
+          "to": "123456789"
+        }
+      }
+    }
+  }
+}
+```
+
+### Restart and verify
+
+Restart the gateway. Check the logs for these three lines in order:
+
+```
+[claude-mem] Observation feed starting — channel: telegram, target: 123456789
+[claude-mem] Connecting to SSE stream at http://localhost:37777/stream
+[claude-mem] Connected to SSE stream
+```
+
+Then run `/claude_mem_feed` in any OpenClaw chat:
+
+```
+Claude-Mem Observation Feed
+Enabled: yes
+Channel: telegram
+Target: 123456789
+Connection: connected
+```
+
+If `Connection` shows `connected`, you're done. Have an agent do some work and watch observations stream to your channel.
+
+## Commands Reference
+
+The plugin registers two commands:
+
+### /claude_mem_status
+
+Reports worker health and current session state.
+
+```
+/claude_mem_status
+```
+
+Output:
+```
+Claude-Mem Worker Status
+Status: ok
+Port: 37777
+Active sessions: 2
+Observation feed: connected
+```
+
+### /claude_mem_feed
+
+Shows observation feed status. Accepts optional `on`/`off` argument.
+
+```
+/claude_mem_feed          — show status
+/claude_mem_feed on       — request enable (update config to persist)
+/claude_mem_feed off      — request disable (update config to persist)
+```
+
+## How It All Works
+
+```
+OpenClaw Gateway
+  │
+  ├── before_agent_start ──→ Sync MEMORY.md + Init session
+  ├── tool_result_persist ──→ Record observation + Re-sync MEMORY.md
+  ├── agent_end ────────────→ Summarize + Complete session
+  └── gateway_start ────────→ Reset session tracking
+                    │
+                    ▼
+         Claude-Mem Worker (localhost:37777)
+           ├── POST /api/sessions/init
+           ├── POST /api/sessions/observations
+           ├── POST /api/sessions/summarize
+           ├── POST /api/sessions/complete
+           ├── GET  /api/context/inject ──→ MEMORY.md content
+           └── GET  /stream ─────────────→ SSE → Messaging channels
+```
+
+### MEMORY.md live sync
+
+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
+
+Updates are fire-and-forget (non-blocking). The agent is never held up waiting for MEMORY.md to write.
+
+### Observation recording
+
+Every tool use (Read, Write, Bash, etc.) is sent to the claude-mem worker as an observation. The worker's AI agent processes it into a structured observation with title, subtitle, facts, concepts, and narrative. Tools prefixed with `memory_` are skipped to avoid recursive recording.
+
+### 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.
+- **`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.
+
+### Observation feed
+
+A background service connects to the worker's SSE stream and forwards `new_observation` events to a configured messaging channel. The connection auto-reconnects with exponential backoff (1s → 30s max).
+
+## Troubleshooting
+
+| Problem | What to check |
+|---------|---------------|
+| Worker health check fails | Is bun installed? (`bun --version`). Is something else on port 37777? (`lsof -i :37777`). Try running directly: `bun plugin/scripts/worker-service.cjs start` |
+| Worker started from Claude Code install but not responding | Check `cd ~/.claude/plugins/marketplaces/thedotmack && npm run worker:status`. May need `npm run worker:restart`. |
+| Worker started from cloned repo but not responding | Check `cd /path/to/claude-mem && npm run worker:status`. Make sure you ran `npm install && npm run build` first. |
+| No MEMORY.md appearing | Check that `syncMemoryFile` is not set to `false`. Verify the agent's event context includes `workspaceDir`. |
+| 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. |
+| `Unknown channel type` in logs | The channel plugin (e.g., telegram) isn't loaded on your gateway. Make sure the channel is configured and running. |
+| `Observation feed disabled` in logs | Set `observationFeed.enabled` to `true` in your config. |
+| `Observation feed misconfigured` in logs | Both `observationFeed.channel` and `observationFeed.to` are required. |
+| No messages in channel despite `connected` | The feed only sends processed observations, not raw tool usage. There's a 1-2 second delay. Make sure the worker is actually processing observations (check http://localhost:37777). |
+
+## Full Config Reference
+
+```json
+{
+  "plugins": {
+    "claude-mem": {
+      "enabled": true,
+      "config": {
+        "project": "openclaw",
+        "syncMemoryFile": true,
+        "workerPort": 37777,
+        "observationFeed": {
+          "enabled": false,
+          "channel": "telegram",
+          "to": "123456789"
+        }
+      }
+    }
+  }
+}
+```
+
+| Field | Type | Default | Description |
+|-------|------|---------|-------------|
+| `project` | string | `"openclaw"` | Project name scoping observations in the database |
+| `syncMemoryFile` | boolean | `true` | Write MEMORY.md to agent workspaces |
+| `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` |
+| `observationFeed.to` | string | — | Target chat/channel/user ID |

openclaw/TESTING.md

@@ -0,0 +1,279 @@
+# OpenClaw Claude-Mem Plugin — Testing Guide
+
+## Quick Start (Docker)
+
+The fastest way to test the plugin is using the pre-built Docker E2E environment:
+
+```bash
+cd openclaw
+
+# Automated test (builds, installs plugin on real OpenClaw, verifies everything)
+./test-e2e.sh
+
+# Interactive shell (for manual exploration)
+./test-e2e.sh --interactive
+
+# Just build the image
+./test-e2e.sh --build-only
+```
+
+---
+
+## Test Layers
+
+### 1. Unit Tests (fastest)
+
+```bash
+cd openclaw
+npm test    # compiles TypeScript, runs 17 tests
+```
+
+Tests plugin registration, service lifecycle, command handling, SSE integration, and all 6 channel types.
+
+### 2. Smoke Test
+
+```bash
+node test-sse-consumer.js
+```
+
+Quick check that the plugin loads and registers its service + command correctly.
+
+### 3. Container Unit Tests (fresh install)
+
+```bash
+./test-container.sh          # Unit tests in clean Docker
+./test-container.sh --full   # Integration tests with mock worker
+```
+
+### 4. E2E on Real OpenClaw (Docker)
+
+```bash
+./test-e2e.sh
+```
+
+This is the most comprehensive test. It:
+1. Uses the official `ghcr.io/openclaw/openclaw:main` Docker image
+2. Installs the plugin via `openclaw plugins install` (same as a real user)
+3. Enables the plugin via `openclaw plugins enable`
+4. Starts a mock claude-mem worker on port 37777
+5. Starts the OpenClaw gateway with plugin config
+6. Verifies the plugin loads, connects to SSE, and processes events
+
+**All 16 checks must pass.**
+
+---
+
+## Human E2E Testing (Interactive Docker)
+
+For manual walkthrough testing, use the interactive Docker mode:
+
+```bash
+./test-e2e.sh --interactive
+```
+
+This drops you into a fully-configured OpenClaw container with the plugin pre-installed.
+
+### Step-by-step inside the container
+
+#### 1. Verify plugin is installed
+
+```bash
+node openclaw.mjs plugins list
+node openclaw.mjs plugins info claude-mem
+node openclaw.mjs plugins doctor
+```
+
+**Expected:**
+- `claude-mem` appears in the plugins list as "enabled" or "loaded"
+- Info shows version 1.0.0, source at `/home/node/.openclaw/extensions/claude-mem/`
+- Doctor reports no issues
+
+#### 2. Inspect plugin files
+
+```bash
+ls -la /home/node/.openclaw/extensions/claude-mem/
+cat /home/node/.openclaw/extensions/claude-mem/openclaw.plugin.json
+cat /home/node/.openclaw/extensions/claude-mem/package.json
+```
+
+**Expected:**
+- `dist/index.js` exists (compiled plugin)
+- `openclaw.plugin.json` has `"id": "claude-mem"` and `"kind": "memory"`
+- `package.json` has `openclaw.extensions` field pointing to `./dist/index.js`
+
+#### 3. Start mock worker
+
+```bash
+node /app/mock-worker.js &
+```
+
+Verify it's running:
+
+```bash
+curl -s http://localhost:37777/health
+# → {"status":"ok"}
+
+curl -s --max-time 3 http://localhost:37777/stream
+# → data: {"type":"connected","message":"Mock worker SSE stream"}
+# → data: {"type":"new_observation","observation":{...}}
+```
+
+#### 4. Configure and start gateway
+
+```bash
+cat > /home/node/.openclaw/openclaw.json << 'EOF'
+{
+  "gateway": {
+    "mode": "local",
+    "auth": {
+      "mode": "token",
+      "token": "e2e-test-token"
+    }
+  },
+  "plugins": {
+    "slots": {
+      "memory": "claude-mem"
+    },
+    "entries": {
+      "claude-mem": {
+        "enabled": true,
+        "config": {
+          "workerPort": 37777,
+          "observationFeed": {
+            "enabled": true,
+            "channel": "telegram",
+            "to": "test-chat-id-12345"
+          }
+        }
+      }
+    }
+  }
+}
+EOF
+
+node openclaw.mjs gateway --allow-unconfigured --verbose --token e2e-test-token
+```
+
+**Expected in gateway logs:**
+- `[claude-mem] OpenClaw plugin loaded — v1.0.0`
+- `[claude-mem] Observation feed starting — channel: telegram, target: test-chat-id-12345`
+- `[claude-mem] Connecting to SSE stream at http://localhost:37777/stream`
+- `[claude-mem] Connected to SSE stream`
+
+#### 5. Run automated verification (optional)
+
+From a second shell in the container (or after stopping the gateway):
+
+```bash
+/bin/bash /app/e2e-verify.sh
+```
+
+---
+
+## Manual E2E (Real OpenClaw + Real Worker)
+
+For testing with a real claude-mem worker and real messaging channel:
+
+### Prerequisites
+
+- OpenClaw gateway installed and configured
+- Claude-Mem worker running on port 37777
+- Plugin built: `cd openclaw && npm run build`
+
+### 1. Install the plugin
+
+```bash
+# Build the plugin
+cd openclaw && npm run build
+
+# Install on OpenClaw (from the openclaw/ directory)
+openclaw plugins install .
+
+# Enable it
+openclaw plugins enable claude-mem
+```
+
+### 2. Configure
+
+Edit `~/.openclaw/openclaw.json` to add plugin config:
+
+```json
+{
+  "plugins": {
+    "entries": {
+      "claude-mem": {
+        "enabled": true,
+        "config": {
+          "workerPort": 37777,
+          "observationFeed": {
+            "enabled": true,
+            "channel": "telegram",
+            "to": "YOUR_CHAT_ID"
+          }
+        }
+      }
+    }
+  }
+}
+```
+
+**Supported channels:** `telegram`, `discord`, `signal`, `slack`, `whatsapp`, `line`
+
+### 3. Restart gateway
+
+```bash
+openclaw restart
+```
+
+**Look for in logs:**
+- `[claude-mem] OpenClaw plugin loaded — v1.0.0`
+- `[claude-mem] Connected to SSE stream`
+
+### 4. Trigger an observation
+
+Start a Claude Code session with claude-mem enabled and perform any action. The worker will emit a `new_observation` SSE event.
+
+### 5. Verify delivery
+
+Check the target messaging channel for:
+
+```
+🧠 Claude-Mem Observation
+**Observation Title**
+Optional subtitle
+```
+
+---
+
+## Troubleshooting
+
+### `api.log is not a function`
+The plugin was built against the wrong API. Ensure `src/index.ts` uses `api.logger.info()` not `api.log()`. Rebuild with `npm run build`.
+
+### Worker not running
+- **Symptom:** `SSE stream error: fetch failed. Reconnecting in 1s`
+- **Fix:** Start the worker: `cd /path/to/claude-mem && npm run build-and-sync`
+
+### Port mismatch
+- **Fix:** Ensure `workerPort` in config matches the worker's actual port (default: 37777)
+
+### Channel not configured
+- **Symptom:** `Observation feed misconfigured — channel or target missing`
+- **Fix:** Add both `channel` and `to` to `observationFeed` in config
+
+### Unknown channel type
+- **Fix:** Use: `telegram`, `discord`, `signal`, `slack`, `whatsapp`, or `line`
+
+### Feed disabled
+- **Symptom:** `Observation feed disabled`
+- **Fix:** Set `observationFeed.enabled: true`
+
+### Messages not arriving
+1. Verify the bot/integration is configured in the target channel
+2. Check the target ID (`to`) is correct
+3. Look for `Failed to send to <channel>` in logs
+4. Test the channel via OpenClaw's built-in tools
+
+### Memory slot conflict
+- **Symptom:** `plugin disabled (memory slot set to "memory-core")`
+- **Fix:** Add `"slots": { "memory": "claude-mem" }` to plugins config

openclaw/e2e-verify.sh

@@ -0,0 +1,265 @@
+#!/usr/bin/env bash
+# e2e-verify.sh — Automated E2E verification for claude-mem plugin on OpenClaw
+#
+# This script verifies the complete plugin installation and operation flow:
+# 1. Plugin is installed and visible in OpenClaw
+# 2. Plugin loads correctly when gateway starts
+# 3. Mock worker SSE stream is consumed by the plugin
+# 4. Observations are received and formatted
+#
+# Exit 0 = all checks passed, Exit 1 = failure
+
+set -euo pipefail
+
+PASS=0
+FAIL=0
+TOTAL=0
+
+pass() {
+  PASS=$((PASS + 1))
+  TOTAL=$((TOTAL + 1))
+  echo "  PASS: $1"
+}
+
+fail() {
+  FAIL=$((FAIL + 1))
+  TOTAL=$((TOTAL + 1))
+  echo "  FAIL: $1"
+}
+
+section() {
+  echo ""
+  echo "=== $1 ==="
+}
+
+# ─── Phase 1: Plugin Discovery ───
+
+section "Phase 1: Plugin Discovery"
+
+# Check plugin is listed
+PLUGIN_LIST=$(node /app/openclaw.mjs plugins list 2>&1)
+if echo "$PLUGIN_LIST" | grep -q "claude-mem"; then
+  pass "Plugin appears in 'plugins list'"
+else
+  fail "Plugin NOT found in 'plugins list'"
+  echo "$PLUGIN_LIST"
+fi
+
+# Check plugin info
+PLUGIN_INFO=$(node /app/openclaw.mjs plugins info claude-mem 2>&1 || true)
+if echo "$PLUGIN_INFO" | grep -qi "claude-mem"; then
+  pass "Plugin info shows claude-mem details"
+else
+  fail "Plugin info failed"
+  echo "$PLUGIN_INFO"
+fi
+
+# Check plugin is enabled
+if echo "$PLUGIN_LIST" | grep -A1 "claude-mem" | grep -qi "enabled\|loaded"; then
+  pass "Plugin is enabled"
+else
+  # Try to check via info
+  if echo "$PLUGIN_INFO" | grep -qi "enabled\|loaded"; then
+    pass "Plugin is enabled (via info)"
+  else
+    fail "Plugin does not appear enabled"
+    echo "$PLUGIN_INFO"
+  fi
+fi
+
+# Check plugin doctor reports no issues
+DOCTOR_OUT=$(node /app/openclaw.mjs plugins doctor 2>&1 || true)
+if echo "$DOCTOR_OUT" | grep -qi "no.*issue\|0 issue"; then
+  pass "Plugin doctor reports no issues"
+else
+  fail "Plugin doctor reports issues"
+  echo "$DOCTOR_OUT"
+fi
+
+# ─── Phase 2: Plugin Files ───
+
+section "Phase 2: Plugin Files"
+
+# Check extension directory exists
+EXTENSIONS_DIR="/home/node/.openclaw/extensions/openclaw-plugin"
+if [ ! -d "$EXTENSIONS_DIR" ]; then
+  # Try alternative naming
+  EXTENSIONS_DIR="/home/node/.openclaw/extensions/claude-mem"
+  if [ ! -d "$EXTENSIONS_DIR" ]; then
+    # Search for it
+    FOUND_DIR=$(find /home/node/.openclaw/extensions/ -name "openclaw.plugin.json" -exec dirname {} \; 2>/dev/null | head -1 || true)
+    if [ -n "$FOUND_DIR" ]; then
+      EXTENSIONS_DIR="$FOUND_DIR"
+    fi
+  fi
+fi
+
+if [ -d "$EXTENSIONS_DIR" ]; then
+  pass "Plugin directory exists: $EXTENSIONS_DIR"
+else
+  fail "Plugin directory not found under /home/node/.openclaw/extensions/"
+  ls -la /home/node/.openclaw/extensions/ 2>/dev/null || echo "  (extensions dir not found)"
+fi
+
+# Check key files exist
+for FILE in "openclaw.plugin.json" "dist/index.js" "package.json"; do
+  if [ -f "$EXTENSIONS_DIR/$FILE" ]; then
+    pass "File exists: $FILE"
+  else
+    fail "File missing: $FILE"
+  fi
+done
+
+# ─── Phase 3: Mock Worker + Plugin Integration ───
+
+section "Phase 3: Mock Worker + Plugin Integration"
+
+# Start mock worker in background
+echo "  Starting mock claude-mem worker..."
+node /app/mock-worker.js &
+MOCK_PID=$!
+
+# Wait for mock worker to be ready
+for i in $(seq 1 10); do
+  if curl -sf http://localhost:37777/health > /dev/null 2>&1; then
+    break
+  fi
+  sleep 0.5
+done
+
+if curl -sf http://localhost:37777/health > /dev/null 2>&1; then
+  pass "Mock worker health check passed"
+else
+  fail "Mock worker health check failed"
+  kill $MOCK_PID 2>/dev/null || true
+fi
+
+# Test SSE stream connectivity (curl with max-time to capture initial SSE frame)
+SSE_TEST=$(curl -s --max-time 2 http://localhost:37777/stream 2>/dev/null || true)
+if echo "$SSE_TEST" | grep -q "connected"; then
+  pass "SSE stream returns connected event"
+else
+  fail "SSE stream did not return connected event"
+  echo "  Got: $(echo "$SSE_TEST" | head -5)"
+fi
+
+# ─── Phase 4: Gateway + Plugin Load ───
+
+section "Phase 4: Gateway Startup with Plugin"
+
+# Create a minimal config that enables the plugin with the mock worker.
+# The memory slot must be set to "claude-mem" to match what `plugins install` configured.
+# Gateway auth is disabled via token for headless testing.
+mkdir -p /home/node/.openclaw
+cat > /home/node/.openclaw/openclaw.json << 'EOFCONFIG'
+{
+  "gateway": {
+    "mode": "local",
+    "auth": {
+      "mode": "token",
+      "token": "e2e-test-token"
+    }
+  },
+  "plugins": {
+    "slots": {
+      "memory": "claude-mem"
+    },
+    "entries": {
+      "claude-mem": {
+        "enabled": true,
+        "config": {
+          "workerPort": 37777,
+          "observationFeed": {
+            "enabled": true,
+            "channel": "telegram",
+            "to": "test-chat-id-12345"
+          }
+        }
+      }
+    }
+  }
+}
+EOFCONFIG
+
+pass "OpenClaw config written with plugin enabled"
+
+# Start gateway in background and capture output
+GATEWAY_LOG="/tmp/gateway.log"
+echo "  Starting OpenClaw gateway (timeout 15s)..."
+OPENCLAW_GATEWAY_TOKEN=e2e-test-token timeout 15 node /app/openclaw.mjs gateway --allow-unconfigured --verbose --token e2e-test-token > "$GATEWAY_LOG" 2>&1 &
+GATEWAY_PID=$!
+
+# Give the gateway time to start and load plugins
+sleep 5
+
+# Check if gateway started
+if kill -0 $GATEWAY_PID 2>/dev/null; then
+  pass "Gateway process is running"
+else
+  fail "Gateway process exited early"
+  echo "  Gateway log:"
+  cat "$GATEWAY_LOG" 2>/dev/null | tail -30
+fi
+
+# Check gateway log for plugin load messages
+if grep -qi "claude-mem" "$GATEWAY_LOG" 2>/dev/null; then
+  pass "Gateway log mentions claude-mem plugin"
+else
+  fail "Gateway log does not mention claude-mem"
+  echo "  Gateway log (last 20 lines):"
+  tail -20 "$GATEWAY_LOG" 2>/dev/null
+fi
+
+# Check for plugin loaded message
+if grep -q "plugin loaded" "$GATEWAY_LOG" 2>/dev/null || grep -q "v1.0.0" "$GATEWAY_LOG" 2>/dev/null; then
+  pass "Plugin load message found in gateway log"
+else
+  fail "Plugin load message not found"
+fi
+
+# Check for observation feed messages
+if grep -qi "observation feed" "$GATEWAY_LOG" 2>/dev/null; then
+  pass "Observation feed activity in gateway log"
+else
+  fail "No observation feed activity detected"
+fi
+
+# Check for SSE connection to mock worker
+if grep -qi "connected.*SSE\|SSE.*stream\|connecting.*SSE" "$GATEWAY_LOG" 2>/dev/null; then
+  pass "SSE connection activity detected"
+else
+  fail "No SSE connection activity in log"
+fi
+
+# ─── Cleanup ───
+
+section "Cleanup"
+kill $GATEWAY_PID 2>/dev/null || true
+kill $MOCK_PID 2>/dev/null || true
+wait $GATEWAY_PID 2>/dev/null || true
+wait $MOCK_PID 2>/dev/null || true
+echo "  Processes stopped."
+
+# ─── Summary ───
+
+echo ""
+echo "==============================="
+echo "  E2E Test Results"
+echo "==============================="
+echo "  Total:  $TOTAL"
+echo "  Passed: $PASS"
+echo "  Failed: $FAIL"
+echo "==============================="
+
+if [ "$FAIL" -gt 0 ]; then
+  echo ""
+  echo "  SOME TESTS FAILED"
+  echo ""
+  echo "  Full gateway log:"
+  cat "$GATEWAY_LOG" 2>/dev/null
+  exit 1
+fi
+
+echo ""
+echo "  ALL TESTS PASSED"
+exit 0

openclaw/openclaw.plugin.json

@@ -0,0 +1,86 @@
+{
+  "id": "claude-mem",
+  "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": "10.4.1",
+  "author": "thedotmack",
+  "homepage": "https://claude-mem.com",
+  "skills": ["skills/make-plan", "skills/do"],
+  "configSchema": {
+    "type": "object",
+    "additionalProperties": false,
+    "properties": {
+      "syncMemoryFile": {
+        "type": "boolean",
+        "default": true,
+        "description": "Automatically sync MEMORY.md on session start"
+      },
+      "workerPort": {
+        "type": "number",
+        "default": 37777,
+        "description": "Port for Claude-Mem worker service"
+      },
+      "project": {
+        "type": "string",
+        "default": "openclaw",
+        "description": "Project name for scoping observations in the memory database"
+      },
+      "observationFeed": {
+        "type": "object",
+        "description": "Live observation feed — streams observations to any OpenClaw channel in real-time",
+        "properties": {
+          "enabled": {
+            "type": "boolean",
+            "default": false,
+            "description": "Enable live observation feed to messaging channels"
+          },
+          "channel": {
+            "type": "string",
+            "description": "Channel type: telegram, discord, signal, slack, whatsapp, line"
+          },
+          "to": {
+            "type": "string",
+            "description": "Target chat/user ID to send observations to"
+          },
+          "botToken": {
+            "type": "string",
+            "description": "Optional dedicated Telegram bot token for the feed (bypasses gateway channel)"
+          },
+          "emojis": {
+            "type": "object",
+            "description": "Emoji personalization for the observation feed. Each agent gets a unique emoji automatically — customize here to override.",
+            "properties": {
+              "primary": {
+                "type": "string",
+                "default": "🦞",
+                "description": "Emoji for the main OpenClaw gateway (project='openclaw')"
+              },
+              "claudeCode": {
+                "type": "string",
+                "default": "⌨️",
+                "description": "Emoji for Claude Code sessions (non-OpenClaw)"
+              },
+              "claudeCodeLabel": {
+                "type": "string",
+                "default": "Claude Code Session",
+                "description": "Display label prefix for Claude Code sessions in the feed (project identifier is appended automatically)"
+              },
+              "default": {
+                "type": "string",
+                "default": "🦀",
+                "description": "Fallback emoji when no match is found"
+              },
+              "agents": {
+                "type": "object",
+                "default": {},
+                "description": "Pin specific emojis to agent IDs (e.g. {\"devops\": \"🔧\"}). Agents not listed here get auto-assigned emojis.",
+                "additionalProperties": { "type": "string" }
+              }
+            }
+          }
+        }
+      }
+    }
+  }
+}

openclaw/package.json

@@ -0,0 +1,20 @@
+{
+  "name": "@openclaw/claude-mem",
+  "version": "1.0.0",
+  "private": true,
+  "type": "module",
+  "main": "dist/index.js",
+  "scripts": {
+    "build": "tsc",
+    "test": "tsc && node --test dist/index.test.js"
+  },
+  "devDependencies": {
+    "@types/node": "^25.2.1",
+    "typescript": "^5.3.0"
+  },
+  "openclaw": {
+    "extensions": [
+      "./dist/index.js"
+    ]
+  }
+}

openclaw/skills/do/SKILL.md

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

openclaw/skills/make-plan/SKILL.md

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

openclaw/src/index.test.ts

@@ -0,0 +1,962 @@
+import { describe, it, beforeEach, afterEach } from "node:test";
+import assert from "node:assert/strict";
+import { createServer, type Server, type IncomingMessage, type ServerResponse } from "node:http";
+import { mkdtemp, readFile, rm } from "fs/promises";
+import { join } from "path";
+import { tmpdir } from "os";
+import claudeMemPlugin from "./index.js";
+
+function createMockApi(pluginConfigOverride: Record<string, any> = {}) {
+  const logs: string[] = [];
+  const sentMessages: Array<{ to: string; text: string; channel: string; opts?: any }> = [];
+
+  let registeredService: any = null;
+  const registeredCommands: Map<string, any> = new Map();
+  const eventHandlers: Map<string, Function[]> = new Map();
+
+  const api = {
+    id: "claude-mem",
+    name: "Claude-Mem (Persistent Memory)",
+    version: "1.0.0",
+    source: "/test/extensions/claude-mem/dist/index.js",
+    config: {},
+    pluginConfig: pluginConfigOverride,
+    logger: {
+      info: (message: string) => { logs.push(message); },
+      warn: (message: string) => { logs.push(message); },
+      error: (message: string) => { logs.push(message); },
+      debug: (message: string) => { logs.push(message); },
+    },
+    registerService: (service: any) => {
+      registeredService = service;
+    },
+    registerCommand: (command: any) => {
+      registeredCommands.set(command.name, command);
+    },
+    on: (event: string, callback: Function) => {
+      if (!eventHandlers.has(event)) {
+        eventHandlers.set(event, []);
+      }
+      eventHandlers.get(event)!.push(callback);
+    },
+    runtime: {
+      channel: {
+        telegram: {
+          sendMessageTelegram: async (to: string, text: string) => {
+            sentMessages.push({ to, text, channel: "telegram" });
+          },
+        },
+        discord: {
+          sendMessageDiscord: async (to: string, text: string) => {
+            sentMessages.push({ to, text, channel: "discord" });
+          },
+        },
+        signal: {
+          sendMessageSignal: async (to: string, text: string) => {
+            sentMessages.push({ to, text, channel: "signal" });
+          },
+        },
+        slack: {
+          sendMessageSlack: async (to: string, text: string) => {
+            sentMessages.push({ to, text, channel: "slack" });
+          },
+        },
+        whatsapp: {
+          sendMessageWhatsApp: async (to: string, text: string, opts?: { verbose: boolean }) => {
+            sentMessages.push({ to, text, channel: "whatsapp", opts });
+          },
+        },
+        line: {
+          sendMessageLine: async (to: string, text: string) => {
+            sentMessages.push({ to, text, channel: "line" });
+          },
+        },
+      },
+    },
+  };
+
+  return {
+    api: api as any,
+    logs,
+    sentMessages,
+    getService: () => registeredService,
+    getCommand: (name?: string) => {
+      if (name) return registeredCommands.get(name);
+      return registeredCommands.get("claude_mem_feed");
+    },
+    getEventHandlers: (event: string) => eventHandlers.get(event) || [],
+    fireEvent: async (event: string, data: any, ctx: any = {}) => {
+      const handlers = eventHandlers.get(event) || [];
+      for (const handler of handlers) {
+        await handler(data, ctx);
+      }
+    },
+  };
+}
+
+describe("claudeMemPlugin", () => {
+  it("registers service, commands, and event handlers on load", () => {
+    const { api, logs, getService, getCommand, getEventHandlers } = createMockApi();
+    claudeMemPlugin(api);
+
+    assert.ok(getService(), "service should be registered");
+    assert.equal(getService().id, "claude-mem-observation-feed");
+    assert.ok(getCommand("claude_mem_feed"), "feed command should be registered");
+    assert.ok(getCommand("claude_mem_status"), "status command should be registered");
+    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("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");
+    assert.ok(logs.some((l) => l.includes("plugin loaded")));
+  });
+
+  describe("service start", () => {
+    it("logs disabled when feed not enabled", async () => {
+      const { api, logs, getService } = createMockApi({});
+      claudeMemPlugin(api);
+
+      await getService().start({});
+      assert.ok(logs.some((l) => l.includes("feed disabled")));
+    });
+
+    it("logs disabled when enabled is false", async () => {
+      const { api, logs, getService } = createMockApi({
+        observationFeed: { enabled: false },
+      });
+      claudeMemPlugin(api);
+
+      await getService().start({});
+      assert.ok(logs.some((l) => l.includes("feed disabled")));
+    });
+
+    it("logs misconfigured when channel is missing", async () => {
+      const { api, logs, getService } = createMockApi({
+        observationFeed: { enabled: true, to: "123" },
+      });
+      claudeMemPlugin(api);
+
+      await getService().start({});
+      assert.ok(logs.some((l) => l.includes("misconfigured")));
+    });
+
+    it("logs misconfigured when to is missing", async () => {
+      const { api, logs, getService } = createMockApi({
+        observationFeed: { enabled: true, channel: "telegram" },
+      });
+      claudeMemPlugin(api);
+
+      await getService().start({});
+      assert.ok(logs.some((l) => l.includes("misconfigured")));
+    });
+  });
+
+  describe("service stop", () => {
+    it("logs disconnection on stop", async () => {
+      const { api, logs, getService } = createMockApi({});
+      claudeMemPlugin(api);
+
+      await getService().stop({});
+      assert.ok(logs.some((l) => l.includes("feed stopped")));
+    });
+  });
+
+  describe("command handler", () => {
+    it("returns not configured when no feedConfig", async () => {
+      const { api, getCommand } = createMockApi({});
+      claudeMemPlugin(api);
+
+      const result = await getCommand().handler({ args: "", channel: "telegram", isAuthorizedSender: true, commandBody: "/claude_mem_feed", config: {} });
+      assert.ok(result.text.includes("not configured"));
+    });
+
+    it("returns status when no args", async () => {
+      const { api, getCommand } = createMockApi({
+        observationFeed: { enabled: true, channel: "telegram", to: "123" },
+      });
+      claudeMemPlugin(api);
+
+      const result = await getCommand().handler({ args: "", channel: "telegram", isAuthorizedSender: true, commandBody: "/claude_mem_feed", config: {} });
+      assert.ok(result.text.includes("Enabled: yes"));
+      assert.ok(result.text.includes("Channel: telegram"));
+      assert.ok(result.text.includes("Target: 123"));
+      assert.ok(result.text.includes("Connection:"));
+    });
+
+    it("handles 'on' argument", async () => {
+      const { api, logs, getCommand } = createMockApi({
+        observationFeed: { enabled: false },
+      });
+      claudeMemPlugin(api);
+
+      const result = await getCommand().handler({ args: "on", channel: "telegram", isAuthorizedSender: true, commandBody: "/claude_mem_feed on", config: {} });
+      assert.ok(result.text.includes("enable requested"));
+      assert.ok(logs.some((l) => l.includes("enable requested")));
+    });
+
+    it("handles 'off' argument", async () => {
+      const { api, logs, getCommand } = createMockApi({
+        observationFeed: { enabled: true },
+      });
+      claudeMemPlugin(api);
+
+      const result = await getCommand().handler({ args: "off", channel: "telegram", isAuthorizedSender: true, commandBody: "/claude_mem_feed off", config: {} });
+      assert.ok(result.text.includes("disable requested"));
+      assert.ok(logs.some((l) => l.includes("disable requested")));
+    });
+
+    it("shows connection state in status output", async () => {
+      const { api, getCommand } = createMockApi({
+        observationFeed: { enabled: false, channel: "slack", to: "#general" },
+      });
+      claudeMemPlugin(api);
+
+      const result = await getCommand().handler({ args: "", channel: "slack", isAuthorizedSender: true, commandBody: "/claude_mem_feed", config: {} });
+      assert.ok(result.text.includes("Connection: disconnected"));
+    });
+  });
+});
+
+describe("Observation I/O event handlers", () => {
+  let workerServer: Server;
+  let workerPort: number;
+  let receivedRequests: Array<{ method: string; url: string; body: any }> = [];
+
+  function startWorkerMock(): Promise<number> {
+    return new Promise((resolve) => {
+      workerServer = createServer((req: IncomingMessage, res: ServerResponse) => {
+        let body = "";
+        req.on("data", (chunk) => { body += chunk.toString(); });
+        req.on("end", () => {
+          let parsedBody: any = null;
+          try { parsedBody = JSON.parse(body); } catch {}
+
+          receivedRequests.push({
+            method: req.method || "GET",
+            url: req.url || "/",
+            body: parsedBody,
+          });
+
+          // Handle different endpoints
+          if (req.url === "/api/health") {
+            res.writeHead(200, { "Content-Type": "application/json" });
+            res.end(JSON.stringify({ status: "ok" }));
+            return;
+          }
+
+          if (req.url === "/api/sessions/init") {
+            res.writeHead(200, { "Content-Type": "application/json" });
+            res.end(JSON.stringify({ sessionDbId: 1, promptNumber: 1, skipped: false }));
+            return;
+          }
+
+          if (req.url === "/api/sessions/observations") {
+            res.writeHead(200, { "Content-Type": "application/json" });
+            res.end(JSON.stringify({ status: "queued" }));
+            return;
+          }
+
+          if (req.url === "/api/sessions/summarize") {
+            res.writeHead(200, { "Content-Type": "application/json" });
+            res.end(JSON.stringify({ status: "queued" }));
+            return;
+          }
+
+          if (req.url === "/api/sessions/complete") {
+            res.writeHead(200, { "Content-Type": "application/json" });
+            res.end(JSON.stringify({ status: "completed" }));
+            return;
+          }
+
+          if (req.url?.startsWith("/api/context/inject")) {
+            res.writeHead(200, { "Content-Type": "text/plain; charset=utf-8" });
+            res.end("# Claude-Mem Context\n\n## Timeline\n- Session 1: Did some work");
+            return;
+          }
+
+          if (req.url === "/stream") {
+            res.writeHead(200, {
+              "Content-Type": "text/event-stream",
+              "Cache-Control": "no-cache",
+              Connection: "keep-alive",
+            });
+            return;
+          }
+
+          res.writeHead(404);
+          res.end();
+        });
+      });
+      workerServer.listen(0, () => {
+        const address = workerServer.address();
+        if (address && typeof address === "object") {
+          resolve(address.port);
+        }
+      });
+    });
+  }
+
+  beforeEach(async () => {
+    receivedRequests = [];
+    workerPort = await startWorkerMock();
+  });
+
+  afterEach(() => {
+    workerServer?.close();
+  });
+
+  it("session_start sends session init to worker", async () => {
+    const { api, logs, fireEvent } = createMockApi({ workerPort });
+    claudeMemPlugin(api);
+
+    await fireEvent("session_start", {
+      sessionId: "test-session-1",
+    }, { sessionKey: "agent-1" });
+
+    // Wait for HTTP request
+    await new Promise((resolve) => setTimeout(resolve, 100));
+
+    const initRequest = receivedRequests.find((r) => r.url === "/api/sessions/init");
+    assert.ok(initRequest, "should send init request to worker");
+    assert.equal(initRequest!.body.project, "openclaw");
+    assert.ok(initRequest!.body.contentSessionId.startsWith("openclaw-agent-1-"));
+    assert.ok(logs.some((l) => l.includes("Session initialized")));
+  });
+
+  it("session_start calls init on worker", async () => {
+    const { api, fireEvent } = createMockApi({ workerPort });
+    claudeMemPlugin(api);
+
+    await fireEvent("session_start", { sessionId: "test-session-1" }, {});
+    await new Promise((resolve) => setTimeout(resolve, 100));
+
+    const initRequests = receivedRequests.filter((r) => r.url === "/api/sessions/init");
+    assert.equal(initRequests.length, 1, "should init on session_start");
+  });
+
+  it("after_compaction re-inits session on worker", async () => {
+    const { api, fireEvent } = createMockApi({ workerPort });
+    claudeMemPlugin(api);
+
+    await fireEvent("after_compaction", { messageCount: 5, compactedCount: 3 }, {});
+    await new Promise((resolve) => setTimeout(resolve, 100));
+
+    const initRequests = receivedRequests.filter((r) => r.url === "/api/sessions/init");
+    assert.equal(initRequests.length, 1, "should re-init after compaction");
+  });
+
+  it("before_agent_start calls init for session privacy check", async () => {
+    const { api, fireEvent } = createMockApi({ workerPort });
+    claudeMemPlugin(api);
+
+    await fireEvent("before_agent_start", { prompt: "hello" }, {});
+    await new Promise((resolve) => setTimeout(resolve, 100));
+
+    const initRequests = receivedRequests.filter((r) => r.url === "/api/sessions/init");
+    assert.equal(initRequests.length, 1, "before_agent_start should init session");
+  });
+
+  it("tool_result_persist sends observation to worker", async () => {
+    const { api, fireEvent } = createMockApi({ workerPort });
+    claudeMemPlugin(api);
+
+    // Establish contentSessionId via session_start
+    await fireEvent("session_start", { sessionId: "s1" }, { sessionKey: "test-agent" });
+    await new Promise((resolve) => setTimeout(resolve, 100));
+
+    // Fire tool result event
+    await fireEvent("tool_result_persist", {
+      toolName: "Read",
+      params: { file_path: "/src/index.ts" },
+      message: {
+        content: [{ type: "text", text: "file contents here..." }],
+      },
+    }, { sessionKey: "test-agent" });
+
+    await new Promise((resolve) => setTimeout(resolve, 100));
+
+    const obsRequest = receivedRequests.find((r) => r.url === "/api/sessions/observations");
+    assert.ok(obsRequest, "should send observation to worker");
+    assert.equal(obsRequest!.body.tool_name, "Read");
+    assert.deepEqual(obsRequest!.body.tool_input, { file_path: "/src/index.ts" });
+    assert.equal(obsRequest!.body.tool_response, "file contents here...");
+    assert.ok(obsRequest!.body.contentSessionId.startsWith("openclaw-test-agent-"));
+  });
+
+  it("tool_result_persist skips memory_ tools", async () => {
+    const { api, fireEvent } = createMockApi({ workerPort });
+    claudeMemPlugin(api);
+
+    await fireEvent("tool_result_persist", {
+      toolName: "memory_search",
+      params: {},
+    }, {});
+
+    await new Promise((resolve) => setTimeout(resolve, 100));
+
+    const obsRequest = receivedRequests.find((r) => r.url === "/api/sessions/observations");
+    assert.ok(!obsRequest, "should skip memory_ tools");
+  });
+
+  it("tool_result_persist truncates long responses", async () => {
+    const { api, fireEvent } = createMockApi({ workerPort });
+    claudeMemPlugin(api);
+
+    const longText = "x".repeat(2000);
+    await fireEvent("tool_result_persist", {
+      toolName: "Bash",
+      params: { command: "ls" },
+      message: {
+        content: [{ type: "text", text: longText }],
+      },
+    }, {});
+
+    await new Promise((resolve) => setTimeout(resolve, 100));
+
+    const obsRequest = receivedRequests.find((r) => r.url === "/api/sessions/observations");
+    assert.ok(obsRequest, "should send observation");
+    assert.equal(obsRequest!.body.tool_response.length, 1000, "should truncate to 1000 chars");
+  });
+
+  it("agent_end sends summarize and complete to worker", async () => {
+    const { api, fireEvent } = createMockApi({ workerPort });
+    claudeMemPlugin(api);
+
+    // Establish session
+    await fireEvent("session_start", { sessionId: "s1" }, { sessionKey: "summarize-test" });
+    await new Promise((resolve) => setTimeout(resolve, 100));
+
+    // Fire agent end
+    await fireEvent("agent_end", {
+      messages: [
+        { role: "user", content: "help me" },
+        { role: "assistant", content: "Here is the solution..." },
+      ],
+    }, { sessionKey: "summarize-test" });
+
+    await new Promise((resolve) => setTimeout(resolve, 100));
+
+    const summarizeRequest = receivedRequests.find((r) => r.url === "/api/sessions/summarize");
+    assert.ok(summarizeRequest, "should send summarize to worker");
+    assert.equal(summarizeRequest!.body.last_assistant_message, "Here is the solution...");
+    assert.ok(summarizeRequest!.body.contentSessionId.startsWith("openclaw-summarize-test-"));
+
+    const completeRequest = receivedRequests.find((r) => r.url === "/api/sessions/complete");
+    assert.ok(completeRequest, "should send complete to worker");
+    assert.ok(completeRequest!.body.contentSessionId.startsWith("openclaw-summarize-test-"));
+  });
+
+  it("agent_end extracts text from array content", async () => {
+    const { api, fireEvent } = createMockApi({ workerPort });
+    claudeMemPlugin(api);
+
+    await fireEvent("session_start", { sessionId: "s1" }, { sessionKey: "array-content" });
+    await new Promise((resolve) => setTimeout(resolve, 100));
+
+    await fireEvent("agent_end", {
+      messages: [
+        {
+          role: "assistant",
+          content: [
+            { type: "text", text: "First part" },
+            { type: "text", text: "Second part" },
+          ],
+        },
+      ],
+    }, { sessionKey: "array-content" });
+
+    await new Promise((resolve) => setTimeout(resolve, 100));
+
+    const summarizeRequest = receivedRequests.find((r) => r.url === "/api/sessions/summarize");
+    assert.ok(summarizeRequest, "should send summarize");
+    assert.equal(summarizeRequest!.body.last_assistant_message, "First part\nSecond part");
+  });
+
+  it("uses custom project name from config", async () => {
+    const { api, fireEvent } = createMockApi({ workerPort, project: "my-project" });
+    claudeMemPlugin(api);
+
+    await fireEvent("session_start", { sessionId: "s1" }, {});
+    await new Promise((resolve) => setTimeout(resolve, 100));
+
+    const initRequest = receivedRequests.find((r) => r.url === "/api/sessions/init");
+    assert.ok(initRequest, "should send init");
+    assert.equal(initRequest!.body.project, "my-project");
+  });
+
+  it("claude_mem_status command reports worker health", async () => {
+    const { api, getCommand } = createMockApi({ workerPort });
+    claudeMemPlugin(api);
+
+    const statusCmd = getCommand("claude_mem_status");
+    assert.ok(statusCmd, "status command should exist");
+
+    const result = await statusCmd.handler({ args: "", channel: "telegram", isAuthorizedSender: true, commandBody: "/claude_mem_status", config: {} });
+    assert.ok(result.text.includes("Status: ok"));
+    assert.ok(result.text.includes(`Port: ${workerPort}`));
+  });
+
+  it("claude_mem_status reports unreachable when worker is down", async () => {
+    workerServer.close();
+    await new Promise((resolve) => setTimeout(resolve, 100));
+
+    const { api, getCommand } = createMockApi({ workerPort: 59999 });
+    claudeMemPlugin(api);
+
+    const statusCmd = getCommand("claude_mem_status");
+    const result = await statusCmd.handler({ args: "", channel: "telegram", isAuthorizedSender: true, commandBody: "/claude_mem_status", config: {} });
+    assert.ok(result.text.includes("unreachable"));
+  });
+
+  it("reuses same contentSessionId for same sessionKey", async () => {
+    const { api, fireEvent } = createMockApi({ workerPort });
+    claudeMemPlugin(api);
+
+    await fireEvent("session_start", { sessionId: "s1" }, { sessionKey: "reuse-test" });
+    await new Promise((resolve) => setTimeout(resolve, 100));
+
+    await fireEvent("tool_result_persist", {
+      toolName: "Read",
+      params: { file_path: "/src/index.ts" },
+      message: { content: [{ type: "text", text: "contents" }] },
+    }, { sessionKey: "reuse-test" });
+
+    await new Promise((resolve) => setTimeout(resolve, 100));
+
+    const initRequest = receivedRequests.find((r) => r.url === "/api/sessions/init");
+    const obsRequest = receivedRequests.find((r) => r.url === "/api/sessions/observations");
+    assert.ok(initRequest && obsRequest, "both requests should exist");
+    assert.equal(
+      initRequest!.body.contentSessionId,
+      obsRequest!.body.contentSessionId,
+      "should reuse contentSessionId for same sessionKey"
+    );
+  });
+});
+
+describe("MEMORY.md context sync", () => {
+  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> {
+    return new Promise((resolve) => {
+      workerServer = createServer((req: IncomingMessage, res: ServerResponse) => {
+        let body = "";
+        req.on("data", (chunk) => { body += chunk.toString(); });
+        req.on("end", () => {
+          let parsedBody: any = null;
+          try { parsedBody = JSON.parse(body); } catch {}
+
+          receivedRequests.push({
+            method: req.method || "GET",
+            url: req.url || "/",
+            body: parsedBody,
+          });
+
+          if (req.url?.startsWith("/api/context/inject")) {
+            res.writeHead(200, { "Content-Type": "text/plain; charset=utf-8" });
+            res.end(contextResponse);
+            return;
+          }
+
+          if (req.url === "/api/sessions/init") {
+            res.writeHead(200, { "Content-Type": "application/json" });
+            res.end(JSON.stringify({ sessionDbId: 1, promptNumber: 1, skipped: false }));
+            return;
+          }
+
+          res.writeHead(200, { "Content-Type": "application/json" });
+          res.end(JSON.stringify({ status: "ok" }));
+        });
+      });
+      workerServer.listen(0, () => {
+        const address = workerServer.address();
+        if (address && typeof address === "object") {
+          resolve(address.port);
+        }
+      });
+    });
+  }
+
+  beforeEach(async () => {
+    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 () => {
+    const { api, logs, fireEvent } = createMockApi({ workerPort });
+    claudeMemPlugin(api);
+
+    await fireEvent("before_agent_start", {
+      prompt: "Help me write a function",
+    }, { sessionKey: "sync-test", workspaceDir: tmpDir });
+
+    await new Promise((resolve) => setTimeout(resolve, 200));
+
+    const contextRequest = receivedRequests.find((r) => r.url?.startsWith("/api/context/inject"));
+    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")));
+  });
+
+  it("syncs MEMORY.md on every before_agent_start call", async () => {
+    const { api, fireEvent } = createMockApi({ workerPort });
+    claudeMemPlugin(api);
+
+    await fireEvent("before_agent_start", {
+      prompt: "First prompt for this agent",
+    }, { sessionKey: "agent-a", 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, "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");
+  });
+
+  it("syncs MEMORY.md on tool_result_persist via fire-and-forget", async () => {
+    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 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");
+
+    // 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));
+
+    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");
+  });
+
+  it("skips MEMORY.md sync when syncMemoryFile is false", async () => {
+    const { api, fireEvent } = createMockApi({ workerPort, syncMemoryFile: false });
+    claudeMemPlugin(api);
+
+    await fireEvent("before_agent_start", {
+      prompt: "Help me write a function",
+    }, { sessionKey: "no-sync", workspaceDir: tmpDir });
+
+    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");
+  });
+
+  it("skips MEMORY.md sync when no workspaceDir in context", async () => {
+    const { api, fireEvent } = createMockApi({ workerPort });
+    claudeMemPlugin(api);
+
+    await fireEvent("before_agent_start", {
+      prompt: "Help me write a function",
+    }, { sessionKey: "no-workspace" });
+
+    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");
+  });
+
+  it("skips writing MEMORY.md when context is empty", async () => {
+    contextResponse = "   ";
+    const { api, logs, fireEvent } = createMockApi({ workerPort });
+    claudeMemPlugin(api);
+
+    await fireEvent("before_agent_start", {
+      prompt: "Help me write a function",
+    }, { sessionKey: "empty-ctx", workspaceDir: tmpDir });
+
+    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");
+  });
+
+  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", {
+      prompt: "Help me write a function",
+    }, { sessionKey: "proj-test", workspaceDir: tmpDir });
+
+    await new Promise((resolve) => setTimeout(resolve, 200));
+
+    const contextRequest = receivedRequests.find((r) => r.url?.startsWith("/api/context/inject"));
+    assert.ok(contextRequest, "should request context");
+    assert.ok(contextRequest!.url!.includes("projects=my-bot"), "should use custom project name");
+  });
+});
+
+describe("SSE stream integration", () => {
+  let server: Server;
+  let serverPort: number;
+  let serverResponses: ServerResponse[] = [];
+
+  function startSSEServer(): Promise<number> {
+    return new Promise((resolve) => {
+      server = createServer((req: IncomingMessage, res: ServerResponse) => {
+        if (req.url !== "/stream") {
+          res.writeHead(404);
+          res.end();
+          return;
+        }
+        res.writeHead(200, {
+          "Content-Type": "text/event-stream",
+          "Cache-Control": "no-cache",
+          Connection: "keep-alive",
+        });
+        serverResponses.push(res);
+      });
+      server.listen(0, () => {
+        const address = server.address();
+        if (address && typeof address === "object") {
+          resolve(address.port);
+        }
+      });
+    });
+  }
+
+  beforeEach(async () => {
+    serverResponses = [];
+    serverPort = await startSSEServer();
+  });
+
+  afterEach(() => {
+    for (const res of serverResponses) {
+      try {
+        res.end();
+      } catch {}
+    }
+    server?.close();
+  });
+
+  it("connects to SSE stream and receives new_observation events", async () => {
+    const { api, logs, sentMessages, getService } = createMockApi({
+      workerPort: serverPort,
+      observationFeed: { enabled: true, channel: "telegram", to: "12345" },
+    });
+    claudeMemPlugin(api);
+
+    await getService().start({});
+
+    // Wait for connection
+    await new Promise((resolve) => setTimeout(resolve, 200));
+
+    assert.ok(logs.some((l) => l.includes("Connecting to SSE stream")));
+
+    // Send an SSE event
+    const observation = {
+      type: "new_observation",
+      observation: {
+        id: 1,
+        title: "Test Observation",
+        subtitle: "Found something interesting",
+        type: "discovery",
+        project: "test",
+        prompt_number: 1,
+        created_at_epoch: Date.now(),
+      },
+      timestamp: Date.now(),
+    };
+
+    for (const res of serverResponses) {
+      res.write(`data: ${JSON.stringify(observation)}\n\n`);
+    }
+
+    // Wait for processing
+    await new Promise((resolve) => setTimeout(resolve, 200));
+
+    assert.equal(sentMessages.length, 1);
+    assert.equal(sentMessages[0].channel, "telegram");
+    assert.equal(sentMessages[0].to, "12345");
+    assert.ok(sentMessages[0].text.includes("Test Observation"));
+    assert.ok(sentMessages[0].text.includes("Found something interesting"));
+
+    await getService().stop({});
+  });
+
+  it("filters out non-observation events", async () => {
+    const { api, sentMessages, getService } = createMockApi({
+      workerPort: serverPort,
+      observationFeed: { enabled: true, channel: "discord", to: "channel-id" },
+    });
+    claudeMemPlugin(api);
+
+    await getService().start({});
+    await new Promise((resolve) => setTimeout(resolve, 200));
+
+    // Send non-observation events
+    for (const res of serverResponses) {
+      res.write(`data: ${JSON.stringify({ type: "processing_status", isProcessing: true })}\n\n`);
+      res.write(`data: ${JSON.stringify({ type: "session_started", sessionId: "abc" })}\n\n`);
+    }
+
+    await new Promise((resolve) => setTimeout(resolve, 200));
+    assert.equal(sentMessages.length, 0, "non-observation events should be filtered");
+
+    await getService().stop({});
+  });
+
+  it("handles observation with null subtitle", async () => {
+    const { api, sentMessages, getService } = createMockApi({
+      workerPort: serverPort,
+      observationFeed: { enabled: true, channel: "telegram", to: "999" },
+    });
+    claudeMemPlugin(api);
+
+    await getService().start({});
+    await new Promise((resolve) => setTimeout(resolve, 200));
+
+    for (const res of serverResponses) {
+      res.write(
+        `data: ${JSON.stringify({
+          type: "new_observation",
+          observation: { id: 2, title: "No Subtitle", subtitle: null },
+          timestamp: Date.now(),
+        })}\n\n`
+      );
+    }
+
+    await new Promise((resolve) => setTimeout(resolve, 200));
+    assert.equal(sentMessages.length, 1);
+    assert.ok(sentMessages[0].text.includes("No Subtitle"));
+    assert.ok(!sentMessages[0].text.includes("null"));
+
+    await getService().stop({});
+  });
+
+  it("handles observation with null title", async () => {
+    const { api, sentMessages, getService } = createMockApi({
+      workerPort: serverPort,
+      observationFeed: { enabled: true, channel: "telegram", to: "999" },
+    });
+    claudeMemPlugin(api);
+
+    await getService().start({});
+    await new Promise((resolve) => setTimeout(resolve, 200));
+
+    for (const res of serverResponses) {
+      res.write(
+        `data: ${JSON.stringify({
+          type: "new_observation",
+          observation: { id: 3, title: null, subtitle: "Has subtitle" },
+          timestamp: Date.now(),
+        })}\n\n`
+      );
+    }
+
+    await new Promise((resolve) => setTimeout(resolve, 200));
+    assert.equal(sentMessages.length, 1);
+    assert.ok(sentMessages[0].text.includes("Untitled"));
+
+    await getService().stop({});
+  });
+
+  it("uses custom workerPort from config", async () => {
+    const { api, logs, getService } = createMockApi({
+      workerPort: serverPort,
+      observationFeed: { enabled: true, channel: "telegram", to: "12345" },
+    });
+    claudeMemPlugin(api);
+
+    await getService().start({});
+    await new Promise((resolve) => setTimeout(resolve, 200));
+
+    assert.ok(logs.some((l) => l.includes(`127.0.0.1:${serverPort}`)));
+
+    await getService().stop({});
+  });
+
+  it("logs unknown channel type", async () => {
+    const { api, logs, sentMessages, getService } = createMockApi({
+      workerPort: serverPort,
+      observationFeed: { enabled: true, channel: "matrix", to: "room-id" },
+    });
+    claudeMemPlugin(api);
+
+    await getService().start({});
+    await new Promise((resolve) => setTimeout(resolve, 200));
+
+    for (const res of serverResponses) {
+      res.write(
+        `data: ${JSON.stringify({
+          type: "new_observation",
+          observation: { id: 4, title: "Test", subtitle: null },
+          timestamp: Date.now(),
+        })}\n\n`
+      );
+    }
+
+    await new Promise((resolve) => setTimeout(resolve, 200));
+    assert.equal(sentMessages.length, 0);
+    assert.ok(logs.some((l) => l.includes("Unsupported channel type: matrix")));
+
+    await getService().stop({});
+  });
+});

openclaw/test-e2e.sh

@@ -0,0 +1,46 @@
+#!/usr/bin/env bash
+# test-e2e.sh — Run E2E test of claude-mem plugin on real OpenClaw
+#
+# Usage:
+#   ./test-e2e.sh              # Automated E2E test (build + run + verify)
+#   ./test-e2e.sh --interactive # Drop into shell for manual testing
+#   ./test-e2e.sh --build-only  # Just build the image, don't run
+set -euo pipefail
+
+cd "$(dirname "$0")"
+
+IMAGE_NAME="openclaw-claude-mem-e2e"
+
+echo "=== Building E2E test image ==="
+echo "  Base: ghcr.io/openclaw/openclaw:main"
+echo "  Plugin: @claude-mem/openclaw-plugin (PR #1012)"
+echo ""
+
+docker build -f Dockerfile.e2e -t "$IMAGE_NAME" .
+
+if [ "${1:-}" = "--build-only" ]; then
+  echo ""
+  echo "Image built: $IMAGE_NAME"
+  echo "Run manually with: docker run --rm $IMAGE_NAME"
+  exit 0
+fi
+
+echo ""
+echo "=== Running E2E verification ==="
+echo ""
+
+if [ "${1:-}" = "--interactive" ]; then
+  echo "Dropping into interactive shell."
+  echo ""
+  echo "Useful commands inside the container:"
+  echo "  node openclaw.mjs plugins list          # Verify plugin is installed"
+  echo "  node openclaw.mjs plugins info claude-mem  # Plugin details"
+  echo "  node openclaw.mjs plugins doctor         # Check for issues"
+  echo "  node /app/mock-worker.js &               # Start mock worker"
+  echo "  node openclaw.mjs gateway --allow-unconfigured --verbose  # Start gateway"
+  echo "  /bin/bash /app/e2e-verify.sh             # Run automated verification"
+  echo ""
+  docker run --rm -it "$IMAGE_NAME" /bin/bash
+else
+  docker run --rm "$IMAGE_NAME"
+fi

openclaw/test-sse-consumer.js

@@ -0,0 +1,106 @@
+/**
+ * Smoke test for OpenClaw claude-mem plugin registration.
+ * Validates the plugin structure works independently of the full OpenClaw runtime.
+ *
+ * Run: node test-sse-consumer.js
+ */
+
+import claudeMemPlugin from "./dist/index.js";
+
+let registeredService = null;
+const registeredCommands = new Map();
+const eventHandlers = new Map();
+const logs = [];
+
+const mockApi = {
+  id: "claude-mem",
+  name: "Claude-Mem (Persistent Memory)",
+  version: "1.0.0",
+  source: "/test/extensions/claude-mem/dist/index.js",
+  config: {},
+  pluginConfig: {},
+  logger: {
+    info: (message) => { logs.push(message); },
+    warn: (message) => { logs.push(message); },
+    error: (message) => { logs.push(message); },
+    debug: (message) => { logs.push(message); },
+  },
+  registerService: (service) => {
+    registeredService = service;
+  },
+  registerCommand: (command) => {
+    registeredCommands.set(command.name, command);
+  },
+  on: (event, callback) => {
+    if (!eventHandlers.has(event)) {
+      eventHandlers.set(event, []);
+    }
+    eventHandlers.get(event).push(callback);
+  },
+  runtime: {
+    channel: {
+      telegram: { sendMessageTelegram: async () => {} },
+      discord: { sendMessageDiscord: async () => {} },
+      signal: { sendMessageSignal: async () => {} },
+      slack: { sendMessageSlack: async () => {} },
+      whatsapp: { sendMessageWhatsApp: async () => {} },
+      line: { sendMessageLine: async () => {} },
+    },
+  },
+};
+
+// Call the default export with mock API
+claudeMemPlugin(mockApi);
+
+// Verify registration
+let failures = 0;
+
+if (!registeredService) {
+  console.error("FAIL: No service was registered");
+  failures++;
+} else if (registeredService.id !== "claude-mem-observation-feed") {
+  console.error(
+    `FAIL: Service ID is "${registeredService.id}", expected "claude-mem-observation-feed"`
+  );
+  failures++;
+} else {
+  console.log("OK: Service registered with id 'claude-mem-observation-feed'");
+}
+
+if (!registeredCommands.has("claude-mem-feed")) {
+  console.error("FAIL: No 'claude-mem-feed' command registered");
+  failures++;
+} else {
+  console.log("OK: Command registered with name 'claude-mem-feed'");
+}
+
+if (!registeredCommands.has("claude-mem-status")) {
+  console.error("FAIL: No 'claude-mem-status' command registered");
+  failures++;
+} else {
+  console.log("OK: Command registered with name 'claude-mem-status'");
+}
+
+const expectedEvents = ["before_agent_start", "tool_result_persist", "agent_end", "gateway_start"];
+for (const event of expectedEvents) {
+  if (!eventHandlers.has(event) || eventHandlers.get(event).length === 0) {
+    console.error(`FAIL: No handler registered for '${event}'`);
+    failures++;
+  } else {
+    console.log(`OK: Event handler registered for '${event}'`);
+  }
+}
+
+if (!logs.some((l) => l.includes("plugin loaded"))) {
+  console.error("FAIL: Plugin did not log a load message");
+  failures++;
+} else {
+  console.log("OK: Plugin logged load message");
+}
+
+if (failures > 0) {
+  console.error(`\nFAIL: ${failures} check(s) failed`);
+  process.exit(1);
+} else {
+  console.log("\nPASS: Plugin registers service, commands, and event handlers correctly");
+}

openclaw/tsconfig.json

@@ -0,0 +1,26 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "ESNext",
+    "moduleResolution": "node",
+    "lib": ["ES2022", "DOM"],
+    "outDir": "./dist",
+    "rootDir": "./src",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true,
+    "resolveJsonModule": true,
+    "declaration": true,
+    "declarationMap": true,
+    "sourceMap": true,
+    "allowSyntheticDefaultImports": true
+  },
+  "include": [
+    "src/**/*"
+  ],
+  "exclude": [
+    "node_modules",
+    "dist"
+  ]
+}

package.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-mem",
-  "version": "9.1.0",
+  "version": "10.5.3",
   "description": "Memory compression system for Claude Code - persist context across sessions",
   "keywords": [
     "claude",
@@ -117,6 +117,16 @@
     "@types/react-dom": "^18.3.0",
     "esbuild": "^0.27.2",
     "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"
   }

plugin/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-mem",
-  "version": "9.1.0",
+  "version": "10.5.3",
   "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,22 @@
         "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
-          },
+          }
+        ]
+      },
+      {
+        "matcher": "startup|clear|compact",
+        "hooks": [
           {
             "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 +45,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 +57,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,17 +68,12 @@
         "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
           },
           {
             "type": "command",
-            "command": "node \"${CLAUDE_PLUGIN_ROOT}/scripts/bun-runner.js\" \"${CLAUDE_PLUGIN_ROOT}/scripts/worker-service.cjs\" hook claude-code session-complete",
+            "command": "_R=\"${CLAUDE_PLUGIN_ROOT}\"; [ -z \"$_R\" ] && _R=\"$HOME/.claude/plugins/marketplaces/thedotmack/plugin\"; node \"$_R/scripts/bun-runner.js\" \"$_R/scripts/worker-service.cjs\" hook claude-code session-complete",
             "timeout": 30
           }
         ]