chore: bump version to 10.0.2

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

.claude-plugin/marketplace.json

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

.github/ISSUE_TEMPLATE/bug_report.md

@@ -7,6 +7,12 @@ assignees: ''
 
 ---
 
+## Before submitting
+
+- [ ] I searched [existing issues](https://github.com/thedotmack/claude-mem/issues) and confirmed this is not a duplicate
+
+---
+
 ## ⚡ Quick Bug Report (Recommended)
 
 **Use the automated bug report generator** for comprehensive diagnostics:

.github/ISSUE_TEMPLATE/feature_request.md

@@ -7,6 +7,12 @@ assignees: ''
 
 ---
 
+## Before submitting
+
+- [ ] I searched [existing issues](https://github.com/thedotmack/claude-mem/issues) and confirmed this is not a duplicate
+
+---
+
 **Is your feature request related to a problem? Please describe.**
 A clear and concise description of what the problem is. Ex. I'm always frustrated when [...]
 

.gitignore

@@ -17,6 +17,7 @@ package-lock.json
 bun.lock
 private/
 datasets/
+Auto Run Docs/
 
 # Generated UI files (built from viewer-template.html)
 src/ui/viewer.html
@@ -30,4 +31,7 @@ src/ui/viewer.html
 
 # Prevent other malformed path directories
 http*/
-https*/
+https*/
+
+# Ignore WebStorm project files (for dinosaur IDE users)
+.idea/

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,70 +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:** Has conflicts, needs rebase
-**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
-
-- [ ] Checkout PR branch `fix/fresh-install-bun-path-818` and rebase onto main to resolve conflicts
-- [ ] Review `bun-runner.js` for correctness across platforms
-- [ ] Verify hooks.json uses correct `node bun-runner.js` pattern
-- [ ] Verify build succeeds after rebase
-- [ ] Merge PR #827 to main
-- [ ] Test on fresh install (uninstall claude-mem, reinstall) to verify Bun is found
-
-## 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

CHANGELOG.md

@@ -2,6 +2,268 @@
 
 All notable changes to claude-mem.
 
+## [v10.0.1] - 2026-02-11
+
+## What's Changed
+
+### OpenClaw Observation Feed
+- Enabled SSE observation feed for OpenClaw agent sessions, allowing real-time streaming of observations to connected OpenClaw clients
+- Fixed `ObservationSSEPayload.project` type to be nullable, preventing type errors when project context is unavailable
+- Added `EnvManager` support for OpenClaw environment configuration
+
+### Build Artifacts
+- Rebuilt worker service and MCP server with latest changes
+
+## [v10.0.0] - 2026-02-11
+
+## OpenClaw Plugin — Persistent Memory for OpenClaw Agents
+
+Claude-mem now has an official [OpenClaw](https://openclaw.ai) plugin, bringing persistent memory to agents running on the OpenClaw gateway. This is a major milestone — claude-mem's memory system is no longer limited to Claude Code sessions.
+
+### What It Does
+
+The plugin bridges claude-mem's observation pipeline with OpenClaw's embedded runner (`pi-embedded`), which calls the Anthropic API directly without spawning a `claude` process. Three core capabilities:
+
+1. **Observation Recording** — Captures every tool call from OpenClaw agents and sends it to the claude-mem worker for AI-powered compression and storage
+2. **MEMORY.md Live Sync** — Writes a continuously-updated memory timeline to each agent's workspace, so agents start every session with full context from previous work
+3. **Observation Feed** — Streams new observations to messaging channels (Telegram, Discord, Slack, Signal, WhatsApp, LINE) in real-time via SSE
+
+### Quick Start
+
+Add claude-mem to your OpenClaw gateway config:
+
+```json
+{
+  "plugins": {
+    "claude-mem": {
+      "enabled": true,
+      "config": {
+        "project": "my-project",
+        "syncMemoryFile": true,
+        "observationFeed": {
+          "enabled": true,
+          "channel": "telegram",
+          "to": "your-chat-id"
+        }
+      }
+    }
+  }
+}
+```
+
+The claude-mem worker service must be running on the same machine (`localhost:37777`).
+
+### Commands
+
+- `/claude-mem-status` — Worker health check, active sessions, feed connection state
+- `/claude-mem-feed` — Show/toggle observation feed status
+- `/claude-mem-feed on|off` — Enable/disable feed
+
+### How the Event Lifecycle Works
+
+```
+OpenClaw Gateway
+  ├── session_start ──────────→ Init claude-mem session
+  ├── before_agent_start ─────→ Sync MEMORY.md + track workspace
+  ├── tool_result_persist ────→ Record observation + re-sync MEMORY.md
+  ├── agent_end ──────────────→ Summarize + complete session
+  ├── session_end ────────────→ Clean up session tracking
+  └── gateway_start ──────────→ Reset all tracking
+```
+
+All observation recording and MEMORY.md syncs are fire-and-forget — they never block the agent.
+
+📖 Full documentation: [OpenClaw Integration Guide](https://docs.claude-mem.ai/docs/openclaw-integration)
+
+---
+
+## Windows Platform Improvements
+
+- **ProcessManager**: Migrated daemon spawning from deprecated WMIC to PowerShell `Start-Process` with `-WindowStyle Hidden`
+- **ChromaSync**: Re-enabled vector search on Windows (was previously disabled entirely)
+- **Worker Service**: Added unified DB-ready gate middleware — all DB-dependent endpoints now wait for initialization instead of returning "Database not initialized" errors
+- **EnvManager**: Switched from fragile allowlist to simple blocklist for subprocess env vars (only strips `ANTHROPIC_API_KEY` per Issue #733)
+
+## Session Management Fixes
+
+- Fixed unbounded session tracking map growth — maps are now cleaned up on `session_end`
+- Session init moved to `session_start` and `after_compaction` hooks for correct lifecycle handling
+
+## SSE Fixes
+
+- Fixed stream URL consistency across the codebase
+- Fixed multi-line SSE data frame parsing (concatenates `data:` lines per SSE spec)
+
+## Issue Triage
+
+Closed 37+ duplicate/stale/invalid issues across multiple triage phases, significantly cleaning up the issue tracker.
+
+## [v9.1.1] - 2026-02-07
+
+## Critical Bug Fix: Worker Initialization Failure
+
+**v9.1.0 was unable to initialize its database on existing installations.** This patch fixes the root cause and several related issues.
+
+### Bug Fixes
+
+- **Fix FOREIGN KEY constraint failure during migration** — The `addOnUpdateCascadeToForeignKeys` migration (schema v21) crashed when orphaned observations existed (observations whose `memory_session_id` has no matching row in `sdk_sessions`). Fixed by disabling FK checks (`PRAGMA foreign_keys = OFF`) during table recreation, following SQLite's recommended migration pattern.
+
+- **Remove hardcoded CHECK constraints on observation type column** — Multiple locations enforced `CHECK(type IN ('decision', 'bugfix', ...))` but the mode system (v8.0.0+) allows custom observation types, causing constraint violations. Removed all 5 occurrences across `SessionStore.ts`, `migrations.ts`, and `migrations/runner.ts`.
+
+- **Fix Express middleware ordering for initialization guard** — The `/api/*` guard middleware that waits for DB initialization was registered AFTER routes, so Express matched routes before the guard. Moved guard middleware registration BEFORE route registrations. Added dedicated early handler for `/api/context/inject` to fail-open during init.
+
+### New
+
+- **Restored mem-search skill** — Recreated `plugin/skills/mem-search/SKILL.md` with the 3-layer workflow (search → timeline → batch fetch) updated for the current MCP tool set.
+
+## [v9.1.0] - 2026-02-07
+
+## v9.1.0 — The Great PR Triage
+
+100 open PRs reviewed, triaged, and resolved. 157 commits, 123 files changed, +6,104/-721 lines. This release focuses on stability, security, and community contributions.
+
+### Highlights
+
+- **100 PR triage**: Reviewed every open PR — merged 48, cherry-picked 13, closed 39 (stale/duplicate/YAGNI)
+- **Fail-open hook architecture**: Hooks no longer block Claude Code prompts when the worker is starting up
+- **DB initialization guard**: All API endpoints now wait for database initialization instead of crashing with "Database not initialized"
+- **Security hardening**: CORS restricted to localhost, XSS defense-in-depth via DOMPurify
+- **3 new features**: Manual memory save, project exclusion, folder exclude setting
+
+---
+
+### Security
+
+- **CORS restricted to localhost** — Worker API no longer accepts cross-origin requests from arbitrary websites. Only localhost/127.0.0.1 origins allowed. (PR #917 by @Spunky84)
+- **XSS defense-in-depth** — Added DOMPurify sanitization to TerminalPreview.tsx viewer component (concept from PR #896)
+
+### New Features
+
+- **Manual memory storage** — New \`save_memory\` MCP tool and \`POST /api/memory/save\` endpoint for explicit memory capture (PR #662 by @darconada, closes #645)
+- **Project exclusion setting** — \`CLAUDE_MEM_EXCLUDED_PROJECTS\` glob patterns to exclude entire projects from tracking (PR #920 by @Spunky84)
+- **Folder exclude setting** — \`CLAUDE_MEM_FOLDER_MD_EXCLUDE\` JSON array to exclude paths from CLAUDE.md generation, fixing Xcode/drizzle build conflicts (PR #699 by @leepokai, closes #620)
+- **Folder CLAUDE.md opt-in** — \`CLAUDE_MEM_FOLDER_CLAUDEMD_ENABLED\` now defaults to \`false\` (opt-in) instead of always-on (PR #913 by @superbiche)
+- **Generate/clean CLI commands** — \`generate\` and \`clean\` commands for CLAUDE.md management with \`--dry-run\` support (PR #657 by @thedotmack)
+- **Ragtime email investigation** — Batch processor for email investigation workflows (PR #863 by @thedotmack)
+
+### Hook Resilience (Fail-Open Architecture)
+
+Hooks no longer block Claude Code when the worker is unavailable or slow:
+
+- **Graceful hook failures** — Hooks exit 0 with empty responses instead of crashing with exit 2 (PR #973 by @farikh)
+- **Fail-open context injection** — Returns empty context during initialization instead of 503 (PR #959 by @rodboev)
+- **Fetch timeouts** — All hook fetch calls have timeouts via \`fetchWithTimeout()\` helper (PR #964 by @rodboev)
+- **Removed stale user-message hook** — Eliminated startup error from incorrectly bundled hook (PR #960 by @rodboev)
+- **DB initialization middleware** — All \`/api/*\` routes now wait for DB init with 30s timeout instead of crashing
+
+### Windows Stability
+
+- **Path spaces fix** — bun-runner.js no longer fails for Windows usernames with spaces (PR #972 by @farikh)
+- **Spawn guard** — 2-minute cooldown prevents repeated worker popup windows on startup failure
+
+### Process & Zombie Management
+
+- **Daemon children cleanup** — Orphan reaper now catches idle daemon child processes (PR #879 by @boaz-robopet)
+- **Expanded orphan cleanup** — Startup cleanup now targets mcp-server.cjs and worker-service.cjs processes
+- **Session-complete hook** — New Stop phase 2 hook removes sessions from active map, enabling effective orphan reaper cleanup (PR #844 by @thusdigital, fixes #842)
+
+### Session Management
+
+- **Prompt-too-long termination** — Sessions terminate cleanly instead of infinite retry loops (PR #934 by @jayvenn21)
+- **Infinite restart prevention** — Max 3 restart attempts with exponential backoff, prevents runaway API costs (PR #693 by @ajbmachon)
+- **Orphaned message fallback** — Messages from terminated sessions drain via Gemini/OpenRouter fallback (PR #937 by @jayvenn21, fixes #936)
+- **Project field backfill** — Sessions correctly scoped when PostToolUse creates session before UserPromptSubmit (PR #940 by @miclip)
+- **Provider-aware recovery** — Startup recovery uses correct provider instead of hardcoding SDKAgent (PR #741 by @licutis)
+- **AbortController reset** — Prevents infinite "Generator aborted" loops after session abort (PR #627 by @TranslateMe)
+- **Stateless provider IDs** — Synthetic memorySessionId generation for Gemini/OpenRouter (concept from PR #615 by @JiehoonKwak)
+- **Duplicate generator prevention** — Legacy init endpoint uses idempotent \`ensureGeneratorRunning()\` (PR #932 by @jayvenn21)
+- **DB readiness wait** — Session-init endpoint waits for database initialization (PR #828 by @rajivsinclair)
+- **Image-only prompt support** — Empty/media prompts use \`[media prompt]\` placeholder (concept from PR #928 by @iammike)
+
+### CLAUDE.md Path & Generation
+
+- **Race condition fix** — Two-pass detection prevents corruption when Claude Code edits CLAUDE.md (concept from PR #974 by @cheapsteak)
+- **Duplicate path prevention** — Detects \`frontend/frontend/\` style nested duplicates (concept from PR #836 by @Glucksberg)
+- **Unsafe directory exclusion** — Blocks generation in \`res/\`, \`.git/\`, \`build/\`, \`node_modules/\`, \`__pycache__/\` (concept from PR #929 by @jayvenn21)
+
+### Chroma/Vector Search
+
+- **ID/metadata alignment fix** — Search results no longer misaligned after deduplication (PR #887 by @abkrim)
+- **Transport zombie prevention** — Connection error handlers now close transport (PR #769 by @jenyapoyarkov)
+- **Zscaler SSL support** — Enterprise environments with SSL inspection now work via combined cert path (PR #884 by @RClark4958)
+
+### Parser & Config
+
+- **Nested XML tag handling** — Parser correctly extracts fields with nested XML content (PR #835 by @Glucksberg)
+- **Graceful empty transcripts** — Transcript parser returns empty string instead of crashing (PR #862 by @DennisHartrampf)
+- **Gemini model name fix** — Corrected \`gemini-3-flash\` → \`gemini-3-flash-preview\` (PR #831 by @Glucksberg)
+- **CLAUDE_CONFIG_DIR support** — Plugin paths respect custom config directory (PR #634 by @Kuroakira, fixes #626)
+- **Env var priority** — \`env > file > defaults\` ordering via \`applyEnvOverrides()\` (PR #712 by @cjpeterein)
+- **Minimum Bun version check** — smart-install.js enforces Bun 1.1.14+ (PR #524 by @quicktime, fixes #519)
+- **Stdin timeout** — JSON self-delimiting detection with 30s safety timeout prevents hook hangs (PR #771 by @rajivsinclair, fixes #727)
+- **FK constraint prevention** — \`ensureMemorySessionIdRegistered()\` guard + \`ON UPDATE CASCADE\` schema migration (PR #889 by @Et9797, fixes #846)
+- **Cursor bun runtime** — Cursor hooks use bun instead of node, fixing bun:sqlite crashes (PR #721 by @polux0)
+
+### Documentation
+
+- **9 README PRs merged**: formatting fixes, Korean/Japanese/Chinese render fixes, documentation link updates, Traditional Chinese + Urdu translations (PRs #953, #898, #864, #637, #636, #894, #907, #691 by @Leonard013, @youngsu5582, @eltociear, @WuMingDao, @fengluodb, @PeterDaveHello, @yasirali646)
+- **Windows setup note** — npm PATH instructions (PR #919 by @kamran-khalid-v9)
+- **Issue templates** — Duplicate check checkbox added (PR #970 by @bmccann36)
+
+### Community Contributors
+
+Thank you to the 35+ contributors whose PRs were reviewed in this release:
+
+@Spunky84, @farikh, @rodboev, @boaz-robopet, @jayvenn21, @ajbmachon, @miclip, @licutis, @TranslateMe, @JiehoonKwak, @rajivsinclair, @iammike, @cheapsteak, @Glucksberg, @abkrim, @jenyapoyarkov, @RClark4958, @DennisHartrampf, @Kuroakira, @cjpeterein, @quicktime, @polux0, @Et9797, @thusdigital, @superbiche, @darconada, @leepokai, @Leonard013, @youngsu5582, @eltociear, @WuMingDao, @fengluodb, @PeterDaveHello, @yasirali646, @kamran-khalid-v9, @bmccann36
+
+---
+
+**Full Changelog**: https://github.com/thedotmack/claude-mem/compare/v9.0.17...v9.1.0
+
+## [v9.0.17] - 2026-02-05
+
+## Bug Fixes
+
+### Fix Fresh Install Bun PATH Resolution (#818)
+
+On fresh installations, hooks would fail because Bun wasn't in PATH until terminal restart. The `smart-install.js` script installs Bun to `~/.bun/bin/bun`, but the current shell session doesn't have it in PATH.
+
+**Fix:** Introduced `bun-runner.js` — a Node.js wrapper that searches common Bun installation locations across all platforms:
+- 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` or fallback paths
+
+All 9 hook definitions updated to use `node bun-runner.js` instead of direct `bun` calls.
+
+**Files changed:**
+- `plugin/scripts/bun-runner.js` — New 88-line Bun discovery script
+- `plugin/hooks/hooks.json` — All hook commands now route through bun-runner
+
+Fixes #818 | PR #827 by @bigphoot
+
+## [v9.0.16] - 2026-02-05
+
+## Bug Fixes
+
+### Fix Worker Startup Timeout (#811, #772, #729)
+
+Resolves the "Worker did not become ready within 15 seconds" timeout error that could prevent hooks from communicating with the worker service.
+
+**Root cause:** `isWorkerHealthy()` and `waitForHealth()` were checking `/api/readiness`, which returns 503 until full initialization completes — including MCP connection setup that can take 5+ minutes. Hooks only have a 15-second timeout window.
+
+**Fix:** Switched to `/api/health` (liveness check), which returns 200 as soon as the HTTP server is listening. This is sufficient for hook communication since the worker accepts requests while background initialization continues.
+
+**Files changed:**
+- `src/shared/worker-utils.ts` — `isWorkerHealthy()` now checks `/api/health`
+- `src/services/infrastructure/HealthMonitor.ts` — `waitForHealth()` now checks `/api/health`
+- `tests/infrastructure/health-monitor.test.ts` — Updated test expectations
+
+### PR Merge Tasks
+- PR #820 merged with full verification pipeline (rebase, code review, build verification, test, manual verification)
+
 ## [v9.0.15] - 2026-02-05
 
 ## Security Fix
@@ -1244,98 +1506,3 @@ Set in ~/.claude-mem/settings.json:
 
 🤖 Generated with [Claude Code](https://claude.com/claude-code)
 
-## [v8.0.0] - 2025-12-23
-
-## 🌍 Major Features
-
-### **Mode System**: Context-aware observation capture tailored to different workflows
-- **Code Development mode** (default): Tracks bugfixes, features, refactors, and more
-- **Email Investigation mode**: Optimized for email analysis workflows
-- Extensible architecture for custom domains
-
-### **28 Language Support**: Full multilingual memory
-- Arabic, Bengali, Chinese, Czech, Danish, Dutch, Finnish, French, German, Greek
-- Hebrew, Hindi, Hungarian, Indonesian, Italian, Japanese, Korean, Norwegian, Polish
-- Portuguese (Brazilian), Romanian, Russian, Spanish, Swedish, Thai, Turkish
-- Ukrainian, Vietnamese
-- All observations, summaries, and narratives generated in your chosen language
-
-### **Inheritance Architecture**: Language modes inherit from base modes
-- Consistent observation types across languages
-- Locale-specific output while maintaining structural integrity
-- JSON-based configuration for easy customization
-
-## 🔧 Technical Improvements
-
-- **ModeManager**: Centralized mode loading and configuration validation
-- **Dynamic Prompts**: SDK prompts now adapt based on active mode
-- **Mode-Specific Icons**: Observation types display contextual icons/emojis per mode
-- **Fail-Fast Error Handling**: Complete removal of silent failures across all layers
-
-## 📚 Documentation
-
-- New docs/public/modes.mdx documenting the mode system
-- 28 translated README files for multilingual community support
-- Updated configuration guide for mode selection
-
-## 🔨 Breaking Changes
-
-- **None** - Mode system is fully backward compatible
-- Default mode is 'code' (existing behavior)
-- Settings: New `CLAUDE_MEM_MODE` option (defaults to 'code')
-
----
-
-**Full Changelog**: https://github.com/thedotmack/claude-mem/compare/v7.4.5...v8.0.0
-**View PR**: https://github.com/thedotmack/claude-mem/pull/412
-
-## [v7.4.5] - 2025-12-21
-
-## Bug Fixes
-
-- Fix missing `formatDateTime` import in SearchManager that broke `get_context_timeline` mem-search function
-
-🤖 Generated with [Claude Code](https://claude.com/claude-code)
-
-## [v7.4.4] - 2025-12-21
-
-## What's Changed
-
-* Code quality: comprehensive nonsense audit cleanup (20 issues) by @thedotmack in #400
-
-**Full Changelog**: https://github.com/thedotmack/claude-mem/compare/v7.4.3...v7.4.4
-
-## [v7.4.3] - 2025-12-20
-
-Added Discord notification script for release announcements.
-
-### Added
-- `scripts/discord-release-notify.js` - Posts formatted release notifications to Discord using webhook URL from `.env`
-- `npm run discord:notify <version>` - New npm script to trigger Discord notifications
-- Updated version-bump skill workflow to include Discord notification step
-
-### Configuration
-Set `DISCORD_UPDATES_WEBHOOK` in your `.env` file to enable release notifications.
-
----
-
-🤖 Generated with [Claude Code](https://claude.com/claude-code)
-
-## [v7.4.2] - 2025-12-20
-
-Patch release v7.4.2
-
-## Changes
-- Refactored worker commands from npm scripts to claude-mem CLI
-- Added path alias script
-- Fixed Windows worker stop/restart reliability (#395)
-- Simplified build commands section in CLAUDE.md
-
-## [v7.4.1] - 2025-12-19
-
-## Bug Fixes
-
-- **MCP Server**: Redirect logs to stderr to preserve JSON-RPC protocol (#396)
-  - MCP uses stdio transport where stdout is reserved for JSON-RPC messages
-  - Console.log was writing startup logs to stdout, causing Claude Desktop to parse log lines as JSON and fail
-

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

@@ -22,6 +22,7 @@
 
 <p align="center">
   <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-br.md">🇧🇷 Português</a> •
   <a href="docs/i18n/README.ko.md">🇰🇷 한국어</a> •
@@ -41,6 +42,7 @@
   <a href="docs/i18n/README.th.md">🇹🇭 ไทย</a> •
   <a href="docs/i18n/README.hi.md">🇮🇳 हिन्दी</a> •
   <a href="docs/i18n/README.bn.md">🇧🇩 বাংলা</a> •
+  <a href="docs/i18n/README.ur.md">🇵🇰 اردو</a> •
   <a href="docs/i18n/README.ro.md">🇷🇴 Română</a> •
   <a href="docs/i18n/README.sv.md">🇸🇪 Svenska</a> •
   <a href="docs/i18n/README.it.md">🇮🇹 Italiano</a> •
@@ -109,9 +111,9 @@
 Start a new Claude Code session in the terminal and enter the following commands:
 
 ```
-> /plugin marketplace add thedotmack/claude-mem
+/plugin marketplace add thedotmack/claude-mem
 
-> /plugin install claude-mem
+/plugin install claude-mem
 ```
 
 Restart Claude Code. Context from previous sessions will automatically appear in new sessions.
@@ -133,7 +135,7 @@ Restart Claude Code. Context from previous sessions will automatically appear in
 
 ## Documentation
 
-📚 **[View Full Documentation](docs/)** - Browse markdown docs on GitHub
+📚 **[View Full Documentation](https://docs.claude-mem.ai/)** - Browse on official website
 
 ### Getting Started
 
@@ -182,7 +184,7 @@ See [Architecture Overview](https://docs.claude-mem.ai/architecture/overview) fo
 
 ## MCP Search Tools
 
-Claude-Mem provides intelligent memory search through **4 MCP tools** following a token-efficient **3-layer workflow pattern**:
+Claude-Mem provides intelligent memory search through **5 MCP tools** following a token-efficient **3-layer workflow pattern**:
 
 **The 3-Layer Workflow:**
 
@@ -195,6 +197,7 @@ Claude-Mem provides intelligent memory search through **4 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:**
@@ -202,7 +205,8 @@ Claude-Mem provides intelligent memory search through **4 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. **`__IMPORTANT`** - Workflow documentation (always visible to Claude)
+4. **`save_memory`** - Manually save a memory/observation for semantic search
+5. **`__IMPORTANT`** - Workflow documentation (always visible to Claude)
 
 **Example Usage:**
 
@@ -214,6 +218,9 @@ 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.
@@ -236,6 +243,17 @@ See **[Beta Features Documentation](https://docs.claude-mem.ai/beta-features)**
 - **uv**: Python package manager for vector search (auto-installed if missing)
 - **SQLite 3**: For persistent storage (bundled)
 
+---
+### Windows Setup Notes
+
+If you see an error like:
+
+```powershell
+npm : The term 'npm' is not recognized as the name of a cmdlet
+```
+
+Make sure Node.js and npm are installed and added to your PATH. Download the latest Node.js installer from https://nodejs.org and restart your terminal after installation.
+
 ---
 
 ## Configuration

docs/i18n/README.ar.md

@@ -13,6 +13,7 @@
 
 <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> •
@@ -32,6 +33,7 @@
   <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> •
@@ -129,7 +131,7 @@ Claude-Mem هو نظام متطور مصمم لضغط وحفظ الذاكرة ل
 
 ## المستندات 
 
-📚 **[عرض التوثيق الكامل](docs/)** - تصفح مستندات markdown على GitHub
+📚 **[عرض التوثيق الكامل](https://docs.claude-mem.ai/)** - تصفح على الموقع الرسمي
 
 ### البدء
 

docs/i18n/README.bn.md

@@ -15,6 +15,7 @@
 
 <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> •
@@ -34,6 +35,7 @@
   <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> •
@@ -126,7 +128,7 @@ Claude Code পুনরায় চালু করুন। পূর্ব
 
 ## ডকুমেন্টেশন
 
-📚 **[সম্পূর্ণ ডকুমেন্টেশন দেখুন](docs/)** - GitHub-এ markdown ডক্স ব্রাউজ করুন
+📚 **[সম্পূর্ণ ডকুমেন্টেশন দেখুন](https://docs.claude-mem.ai/)** - অফিসিয়াল ওয়েবসাইটে ব্রাউজ করুন
 
 ### শুরু করা
 

docs/i18n/README.cs.md

@@ -15,6 +15,7 @@
 
 <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> •
@@ -34,6 +35,7 @@
   <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> •
@@ -126,7 +128,7 @@ Restartujte Claude Code. Kontext z předchozích sezení se automaticky objeví
 
 ## Dokumentace
 
-📚 **[Zobrazit kompletní dokumentaci](docs/)** - Procházejte dokumentaci v markdown na GitHubu
+📚 **[Zobrazit kompletní dokumentaci](https://docs.claude-mem.ai/)** - Procházet na oficiálních stránkách
 
 ### Začínáme
 

docs/i18n/README.da.md

@@ -15,6 +15,7 @@
 
 <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> •
@@ -34,6 +35,7 @@
   <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> •
@@ -126,7 +128,7 @@ Genstart Claude Code. Kontekst fra tidligere sessioner vil automatisk vises i ny
 
 ## Dokumentation
 
-📚 **[Se Fuld Dokumentation](docs/)** - Gennemse markdown-dokumenter på GitHub
+📚 **[Se Fuld Dokumentation](https://docs.claude-mem.ai/)** - Gennemse på den officielle hjemmeside
 
 ### Kom Godt I Gang
 

docs/i18n/README.de.md

@@ -15,6 +15,7 @@
 
 <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> •
@@ -34,6 +35,7 @@
   <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> •
@@ -126,7 +128,7 @@ Starten Sie Claude Code neu. Kontext aus vorherigen Sitzungen wird automatisch i
 
 ## Dokumentation
 
-📚 **[Vollständige Dokumentation anzeigen](docs/)** - Markdown-Dokumentation auf GitHub durchsuchen
+📚 **[Vollständige Dokumentation anzeigen](https://docs.claude-mem.ai/)** - Auf der offiziellen Website durchsuchen
 
 ### Erste Schritte
 

docs/i18n/README.el.md

@@ -15,6 +15,7 @@
 
 <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> •
@@ -34,6 +35,7 @@
   <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> •
@@ -126,7 +128,7 @@
 
 ## Τεκμηρίωση
 
-📚 **[Προβολή Πλήρους Τεκμηρίωσης](docs/)** - Περιήγηση στα markdown έγγραφα στο GitHub
+📚 **[Προβολή Πλήρους Τεκμηρίωσης](https://docs.claude-mem.ai/)** - Περιήγηση στον επίσημο ιστότοπο
 
 ### Ξεκινώντας
 

docs/i18n/README.es.md

@@ -16,6 +16,7 @@
 
 <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> •
@@ -35,6 +36,7 @@
   <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> •
@@ -127,7 +129,7 @@ Reinicia Claude Code. El contexto de sesiones anteriores aparecerá automáticam
 
 ## Documentación
 
-📚 **[Ver Documentación Completa](docs/)** - Explora documentos markdown en GitHub
+📚 **[Ver Documentación Completa](https://docs.claude-mem.ai/)** - Navegar en el sitio web oficial
 
 ### Primeros Pasos
 

docs/i18n/README.fi.md

@@ -14,6 +14,7 @@
 
 <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> •
@@ -33,6 +34,7 @@
   <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> •
@@ -125,7 +127,7 @@ Käynnistä Claude Code uudelleen. Aiempien istuntojen konteksti ilmestyy automa
 
 ## Dokumentaatio
 
-📚 **[Näytä täydellinen dokumentaatio](docs/)** - Selaa markdown-dokumentteja GitHubissa
+📚 **[Näytä täydellinen dokumentaatio](https://docs.claude-mem.ai/)** - Selaa virallisella verkkosivustolla
 
 ### Aloitus
 

docs/i18n/README.fr.md

@@ -15,6 +15,7 @@
 
 <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> •
@@ -34,6 +35,7 @@
   <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> •
@@ -126,7 +128,7 @@ Redémarrez Claude Code. Le contexte des sessions précédentes apparaîtra auto
 
 ## Documentation
 
-📚 **[Voir la documentation complète](docs/)** - Parcourez la documentation markdown sur GitHub
+📚 **[Voir la documentation complète](https://docs.claude-mem.ai/)** - Parcourir sur le site officiel
 
 ### Pour commencer
 

docs/i18n/README.he.md

@@ -14,6 +14,7 @@
 
 <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> •
@@ -33,6 +34,7 @@
   <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> •
@@ -125,7 +127,7 @@
 
 ## תיעוד
 
-📚 **[צפה בתיעוד המלא](docs/)** - עיין במסמכי markdown ב-GitHub
+📚 **[צפה בתיעוד המלא](https://docs.claude-mem.ai/)** - דפדף באתר הרשמי
 
 ### תחילת העבודה
 

docs/i18n/README.hi.md

@@ -15,6 +15,7 @@
 
 <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> •
@@ -34,6 +35,7 @@
   <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> •
@@ -126,7 +128,7 @@ Claude Code को पुनः आरंभ करें। पिछले स
 
 ## दस्तावेज़ीकरण
 
-📚 **[पूर्ण दस्तावेज़ीकरण देखें](docs/)** - GitHub पर markdown दस्तावेज़ ब्राउज़ करें
+📚 **[पूर्ण दस्तावेज़ीकरण देखें](https://docs.claude-mem.ai/)** - आधिकारिक वेबसाइट पर ब्राउज़ करें
 
 ### शुरुआत करना
 

docs/i18n/README.hu.md

@@ -15,6 +15,7 @@
 
 <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> •
@@ -34,6 +35,7 @@
   <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> •
@@ -126,7 +128,7 @@ Indítsa újra a Claude Code-ot. A korábbi munkamenetek kontextusa automatikusa
 
 ## Dokumentáció
 
-📚 **[Teljes dokumentáció megtekintése](docs/)** - Markdown dokumentumok böngészése GitHub-on
+📚 **[Teljes dokumentáció megtekintése](https://docs.claude-mem.ai/)** - Böngészés a hivatalos weboldalon
 
 ### Első lépések
 

docs/i18n/README.id.md

@@ -15,6 +15,7 @@
 
 <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> •
@@ -34,6 +35,7 @@
   <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> •
@@ -126,7 +128,7 @@ Restart Claude Code. Konteks dari sesi sebelumnya akan secara otomatis muncul di
 
 ## Dokumentasi
 
-📚 **[Lihat Dokumentasi Lengkap](docs/)** - Telusuri dokumen markdown di GitHub
+📚 **[Lihat Dokumentasi Lengkap](https://docs.claude-mem.ai/)** - Jelajahi di situs web resmi
 
 ### Memulai
 

docs/i18n/README.it.md

@@ -15,6 +15,7 @@
 
 <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> •
@@ -34,6 +35,7 @@
   <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> •
@@ -126,7 +128,7 @@ Riavvia Claude Code. Il contesto delle sessioni precedenti apparirà automaticam
 
 ## Documentazione
 
-📚 **[Visualizza Documentazione Completa](docs/)** - Sfoglia i documenti markdown su GitHub
+📚 **[Visualizza Documentazione Completa](https://docs.claude-mem.ai/)** - Sfoglia sul sito ufficiale
 
 ### Per Iniziare
 

docs/i18n/README.ja.md

@@ -15,6 +15,7 @@
 
 <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> •
@@ -34,6 +35,7 @@
   <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> •
@@ -126,7 +128,7 @@ Claude Codeを再起動します。以前のセッションからのコンテキ
 
 ## ドキュメント
 
-📚 **[完全なドキュメントを見る](docs/)** - GitHubでマークダウンドキュメントを閲覧
+📚 **[完全なドキュメントを見る](https://docs.claude-mem.ai/)** - 公式ウェブサイトで閲覧
 
 ### はじめに
 
@@ -212,7 +214,7 @@ Claude-Memは、過去の作業について尋ねると自動的に呼び出さ
 
 Claude-Memは、**Endless Mode**(拡張セッション用の生体模倣メモリアーキテクチャ)などの実験的機能を備えた**ベータチャネル**を提供します。http://localhost:37777 → SettingsのWebビューアUIから安定版とベータ版を切り替えます。
 
-Endless Modeと試用方法の詳細については、**[ベータ機能ドキュメント](https://docs.claude-mem.ai/beta-features)**を参照してください。
+Endless Modeと試用方法の詳細については、**[ベータ機能ドキュメント](https://docs.claude-mem.ai/beta-features)** を参照してください。
 
 ---
 
@@ -230,13 +232,13 @@ Endless Modeと試用方法の詳細については、**[ベータ機能ドキ
 
 設定は`~/.claude-mem/settings.json`で管理されます(初回実行時にデフォルト値で自動作成)。AIモデル、ワーカーポート、データディレクトリ、ログレベル、コンテキスト注入設定を構成します。
 
-利用可能なすべての設定と例については、**[設定ガイド](https://docs.claude-mem.ai/configuration)**を参照してください。
+利用可能なすべての設定と例については、**[設定ガイド](https://docs.claude-mem.ai/configuration)** を参照してください。
 
 ---
 
 ## 開発
 
-ビルド手順、テスト、コントリビューションワークフローについては、**[開発ガイド](https://docs.claude-mem.ai/development)**を参照してください。
+ビルド手順、テスト、コントリビューションワークフローについては、**[開発ガイド](https://docs.claude-mem.ai/development)** を参照してください。
 
 ---
 
@@ -244,7 +246,7 @@ Endless Modeと試用方法の詳細については、**[ベータ機能ドキ
 
 問題が発生した場合は、Claudeに問題を説明すると、troubleshootスキルが自動的に診断して修正を提供します。
 
-よくある問題と解決策については、**[トラブルシューティングガイド](https://docs.claude-mem.ai/troubleshooting)**を参照してください。
+よくある問題と解決策については、**[トラブルシューティングガイド](https://docs.claude-mem.ai/troubleshooting)** を参照してください。
 
 ---
 
@@ -286,7 +288,7 @@ Copyright (C) 2025 Alex Newman (@thedotmack). All rights reserved.
 - 派生作品もAGPL-3.0の下でライセンスする必要があります
 - このソフトウェアには保証がありません
 
-**Ragtimeに関する注意**: `ragtime/`ディレクトリは**PolyForm Noncommercial License 1.0.0**の下で個別にライセンスされています。詳細は[ragtime/LICENSE](ragtime/LICENSE)を参照してください。
+**Ragtimeに関する注意**: `ragtime/`ディレクトリは **PolyForm Noncommercial License 1.0.0** の下で個別にライセンスされています。詳細は[ragtime/LICENSE](ragtime/LICENSE)を参照してください。
 
 ---
 
@@ -299,4 +301,4 @@ Copyright (C) 2025 Alex Newman (@thedotmack). All rights reserved.
 
 ---
 
-**Claude Agent SDKで構築** | **Claude Codeで動作** | **TypeScriptで作成**
+**Claude Agent SDKで構築** | **Claude Codeで動作** | **TypeScriptで作成**

docs/i18n/README.ko.md

@@ -15,6 +15,7 @@
 
 <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> •
@@ -34,6 +35,7 @@
   <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> •
@@ -114,19 +116,19 @@ Claude Code를 재시작하세요. 이전 세션의 컨텍스트가 자동으로
 - 🧠 **지속적인 메모리** - 세션 간 컨텍스트 유지
 - 📊 **점진적 공개** - 토큰 비용 가시성을 갖춘 계층화된 메모리 검색
 - 🔍 **스킬 기반 검색** - mem-search 스킬로 프로젝트 기록 쿼리
-- 🖥️ **웹 뷰어 UI** - http://localhost:37777에서 실시간 메모리 스트림 확인
+- 🖥️ **웹 뷰어 UI** - http://localhost:37777 에서 실시간 메모리 스트림 확인
 - 💻 **Claude Desktop 스킬** - Claude Desktop 대화에서 메모리 검색
 - 🔒 **개인정보 제어** - `<private>` 태그를 사용하여 민감한 콘텐츠를 저장소에서 제외
 - ⚙️ **컨텍스트 설정** - 주입되는 컨텍스트에 대한 세밀한 제어
 - 🤖 **자동 작동** - 수동 개입 불필요
-- 🔗 **인용** - ID로 과거 관찰 참조 (http://localhost:37777/api/observation/{id}를 통해 액세스하거나 http://localhost:37777의 웹 뷰어에서 모두 보기)
+- 🔗 **인용** - ID로 과거 관찰 참조 (http://localhost:37777/api/observation/{id} 를 통해 액세스하거나 http://localhost:37777 의 웹 뷰어에서 모두 보기)
 - 🧪 **베타 채널** - 버전 전환을 통해 Endless Mode와 같은 실험적 기능 사용
 
 ---
 
 ## 문서
 
-📚 **[전체 문서 보기](docs/)** - GitHub에서 마크다운 문서 탐색
+📚 **[전체 문서 보기](https://docs.claude-mem.ai/)** - 공식 웹사이트에서 찾아보기
 
 ### 시작하기
 

docs/i18n/README.nl.md

@@ -14,6 +14,7 @@
 
 <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> •
@@ -33,6 +34,7 @@
   <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> •
@@ -125,7 +127,7 @@ Herstart Claude Code. Context van eerdere sessies verschijnt automatisch in nieu
 
 ## Documentatie
 
-📚 **[Bekijk Volledige Documentatie](docs/)** - Blader door markdown documenten op GitHub
+📚 **[Bekijk Volledige Documentatie](https://docs.claude-mem.ai/)** - Bladeren op de officiële website
 
 ### Aan de Slag
 

docs/i18n/README.no.md

@@ -15,6 +15,7 @@
 
 <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> •
@@ -34,6 +35,7 @@
   <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> •
@@ -126,7 +128,7 @@ Start Claude Code på nytt. Kontekst fra tidligere økter vil automatisk vises i
 
 ## Dokumentasjon
 
-📚 **[Se Full Dokumentasjon](docs/)** - Bla gjennom markdown-dokumenter på GitHub
+📚 **[Se Full Dokumentasjon](https://docs.claude-mem.ai/)** - Bla gjennom på det offisielle nettstedet
 
 ### Komme I Gang
 

docs/i18n/README.pl.md

@@ -14,6 +14,7 @@
 
 <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> •
@@ -33,6 +34,7 @@
   <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> •
@@ -125,7 +127,7 @@ Uruchom ponownie Claude Code. Kontekst z poprzednich sesji automatycznie pojawi
 
 ## Dokumentacja
 
-📚 **[Wyświetl Pełną Dokumentację](docs/)** - Przeglądaj dokumentację markdown na GitHub
+📚 **[Wyświetl Pełną Dokumentację](https://docs.claude-mem.ai/)** - Przeglądaj na oficjalnej stronie
 
 ### Pierwsze Kroki
 

docs/i18n/README.pt-br.md

@@ -15,6 +15,7 @@
 
 <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> •
@@ -34,6 +35,7 @@
   <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> •
@@ -126,7 +128,7 @@ Reinicie o Claude Code. O contexto de sessões anteriores aparecerá automaticam
 
 ## Documentação
 
-📚 **[Ver Documentação Completa](docs/)** - Navegue pelos documentos markdown no GitHub
+📚 **[Ver Documentação Completa](https://docs.claude-mem.ai/)** - Navegar no site oficial
 
 ### Começando
 

docs/i18n/README.ro.md

@@ -15,6 +15,7 @@
 
 <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> •
@@ -34,6 +35,7 @@
   <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> •
@@ -126,7 +128,7 @@ Reporniți Claude Code. Contextul din sesiunile anterioare va apărea automat î
 
 ## Documentație
 
-📚 **[Vizualizați Documentația Completă](docs/)** - Răsfoiți documentele markdown pe GitHub
+📚 **[Vizualizați Documentația Completă](https://docs.claude-mem.ai/)** - Răsfoiți pe site-ul oficial
 
 ### Introducere
 

docs/i18n/README.ru.md

@@ -15,6 +15,7 @@
 
 <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> •
@@ -34,6 +35,7 @@
   <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> •
@@ -126,7 +128,7 @@
 
 ## Документация
 
-📚 **[Просмотреть полную документацию](docs/)** - Просмотр markdown-документов на GitHub
+📚 **[Просмотреть полную документацию](https://docs.claude-mem.ai/)** - Просмотр на официальном сайте
 
 ### Начало работы
 

docs/i18n/README.sv.md

@@ -15,6 +15,7 @@
 
 <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> •
@@ -34,6 +35,7 @@
   <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> •
@@ -126,7 +128,7 @@ Starta om Claude Code. Kontext från tidigare sessioner kommer automatiskt att v
 
 ## Dokumentation
 
-📚 **[Visa fullständig dokumentation](docs/)** - Bläddra bland markdown-dokument på GitHub
+📚 **[Visa fullständig dokumentation](https://docs.claude-mem.ai/)** - Bläddra på den officiella webbplatsen
 
 ### Komma igång
 

docs/i18n/README.th.md

@@ -14,6 +14,7 @@
 
 <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> •
@@ -33,6 +34,7 @@
   <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> •
@@ -125,7 +127,7 @@
 
 ## เอกสาร
 
-📚 **[ดูเอกสารฉบับเต็ม](docs/)** - เรียกดูเอกสาร markdown บน GitHub
+📚 **[ดูเอกสารฉบับเต็ม](https://docs.claude-mem.ai/)** - เรียกดูบนเว็บไซต์อย่างเป็นทางการ
 
 ### เริ่มต้นใช้งาน
 

docs/i18n/README.tr.md

@@ -14,6 +14,7 @@
 
 <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> •
@@ -33,6 +34,7 @@
   <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> •
@@ -125,7 +127,7 @@ Claude Code'u yeniden başlatın. Önceki oturumlardaki bağlam otomatik olarak
 
 ## Dokümantasyon
 
-📚 **[Tam Dokümantasyonu Görüntüle](docs/)** - GitHub'da markdown dökümanlarına göz atın
+📚 **[Tam Dokümantasyonu Görüntüle](https://docs.claude-mem.ai/)** - Resmi web sitesinde göz atın
 
 ### Başlarken
 

docs/i18n/README.uk.md

@@ -15,6 +15,7 @@
 
 <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> •
@@ -34,6 +35,7 @@
   <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> •
@@ -126,7 +128,7 @@
 
 ## Документація
 
-📚 **[Переглянути повну документацію](docs/)** - Переглядайте markdown документи на GitHub
+📚 **[Переглянути повну документацію](https://docs.claude-mem.ai/)** - Переглянути на офіційному сайті
 
 ### Початок роботи
 

docs/i18n/README.ur.md

@@ -0,0 +1,311 @@
+<section dir="rtl">
+🌐 یہ ایک خودکار ترجمہ ہے۔ کمیونٹی کی اصلاحات کا خیر مقدم ہے!
+
+---
+<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" dir="ltr">
+  <a href="README.zh.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.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"><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="#تیز-رفتار-شروعات">تیز رفتار شروعات</a> •
+  <a href="#یہ-کیسے-کام-کرتا-ہے">یہ کیسے کام کرتا ہے</a> •
+  <a href="#تلاش-کے-اوزار">تلاش کے اوزار</a> •
+  <a href="#دستاویزات">دستاویزات</a> •
+  <a href="#ترتیبات">ترتیبات</a> •
+  <a href="#مسائل-کی-تشخیص">مسائل کی تشخیص</a> •
+  <a href="#لائسنس">لائسنس</a>
+</p>
+
+<p align="center">
+  Claude-Mem خودکار طور پر ٹول کے استعمال کے بعد کے مشاہدات کو ریکارڈ کرتا ہے، سیمانٹک خلاصے تیار کرتا ہے اور انہیں مستقبل کے سیشنز میں دستیاب کرتا ہے تاکہ آپ سیشن میں براہ راست تناسب محفوظ رہے۔ یہ Claude کو سیشن ختم ہونے یا دوبارہ جڑنے کے بعد بھی منصوبے کے بارے میں معلومات کی مسلسلیت برقرار رکھنے کے قابل بناتا ہے۔
+</p>
+
+---
+
+## تیز رفتار شروعات
+
+ٹرمنل میں نیا Claude Code سیشن شروع کریں اور ہیں کمانڈز درج کریں:
+
+```
+> /plugin marketplace add thedotmack/claude-mem
+
+> /plugin install claude-mem
+```
+
+Claude Code کو دوبارہ شروع کریں۔ سابقہ سیشن کا تناسب خودکار طور پر نئے سیشن میں موجود ہوگا۔
+
+**اہم خصوصیات:**
+
+- 🧠 **مستقل میموری** - تناسب سیشن کے دوران برقرار رہتا ہے
+- 📊 **بتدریج ظہور** - لیئرڈ میموری کی بازیافت ٹوکن کی لاگت کی نمائندگی کے ساتھ
+- 🔍 **کمکردہ تلاش** - mem-search مہارت کے ساتھ اپنے منصوبے کی تاریخ میں تلاش کریں
+- 🖥️ **ویب ویور یو آئی** - http://localhost:37777 پر حقیقی وقت میموری اسٹریم
+- 💻 **Claude Desktop مہارت** - Claude Desktop بات چیت سے میموری تلاش کریں
+- 🔒 **رازداری کے کنٹرولز** - حساس مواد کو ذخیرہ سے خارج کرنے کے لیے `<private>` ٹیگ استعمال کریں
+- ⚙️ **تناسب کی ترتیبات** - کون سا تناسب انجیکٹ کیا جائے اس پر باریک کنٹرول
+- 🤖 **خودکار آپریشن** - کسی دستی مداخلت کی ضرورت نہیں
+- 🔗 **حوالہ** - ID کے ذریعے سابقہ مشاہدات کا حوالہ دیں (http://localhost:37777/api/observation/{id} کے ذریعے رسائی حاصل کریں یا تمام کو http://localhost:37777 پر ویب ویور میں دیکھیں)
+- 🧪 **بیٹا چینل** - ورژن تبدیل کرنے کے ذریعے Endless Mode جیسی تجرباتی خصوصیات آزمائیں
+
+---
+
+## دستاویزات
+
+📚 **[مکمل دستاویزات دیکھیں](docs/)** - GitHub پر markdown ڈاکس کو براؤز کریں
+
+### شروعات کرنا
+
+- **[انسٹالیشن گائیڈ](https://docs.claude-mem.ai/installation)** - تیز رفتار شروعات اور اعلیٰ درجے کی انسٹالیشن
+- **[استعمال گائیڈ](https://docs.claude-mem.ai/usage/getting-started)** - Claude-Mem خودکار طور پر کیسے کام کرتا ہے
+- **[تلاش کے اوزار](https://docs.claude-mem.ai/usage/search-tools)** - قدرتی زبان کے ساتھ اپنے منصوبے کی تاریخ میں تلاش کریں
+- **[بیٹا خصوصیات](https://docs.claude-mem.ai/beta-features)** - Endless Mode جیسی تجرباتی خصوصیات آزمائیں
+
+### بہترین طریقہ کار
+
+- **[تناسب انجینیئرنگ](https://docs.claude-mem.ai/context-engineering)** - AI ایجنٹ کے تناسب کی اہمیت کے اصول
+- **[بتدریج ظہور](https://docs.claude-mem.ai/progressive-disclosure)** - Claude-Mem کے تناسب کی تیاری کی حکمت عملی کے پیچھے فلسفہ
+
+### تعمیر
+
+- **[جائزہ](https://docs.claude-mem.ai/architecture/overview)** - نظام کے اجزاء اور ڈیٹا کے بہاؤ
+- **[تعمیر کا ارتقاء](https://docs.claude-mem.ai/architecture-evolution)** - v3 سے v5 تک کا سفر
+- **[ہکس تعمیر](https://docs.claude-mem.ai/hooks-architecture)** - Claude-Mem لائف سائیکل ہکس کا استعمال کیسے کرتا ہے
+- **[ہکس حوالہ](https://docs.claude-mem.ai/architecture/hooks)** - 7 ہک اسکرپٹس کی تشریح
+- **[ورکر سروس](https://docs.claude-mem.ai/architecture/worker-service)** - HTTP API اور Bun انتظام
+- **[ڈیٹا بیس](https://docs.claude-mem.ai/architecture/database)** - SQLite اسکیما اور FTS5 تلاش
+- **[تلاش تعمیر](https://docs.claude-mem.ai/architecture/search-architecture)** - Chroma ویکٹر ڈیٹا بیس کے ساتھ ہائبرڈ تلاش
+
+### ترتیبات اور ترقی
+
+- **[ترتیبات](https://docs.claude-mem.ai/configuration)** - ماحول کے متغیرات اور سیٹنگز
+- **[ترقی](https://docs.claude-mem.ai/development)** - تعمیر، جانچ، حصہ داری
+- **[مسائل کی تشخیص](https://docs.claude-mem.ai/troubleshooting)** - عام مسائل اور حل
+
+---
+
+## یہ کیسے کام کرتا ہے
+
+**اہم اجزاء:**
+
+1. **5 لائف سائیکل ہکس** - SessionStart، UserPromptSubmit، PostToolUse، Stop، SessionEnd (6 ہک اسکرپٹس)
+2. **سمارٹ انسٹالیشن** - کیش شدہ منحصرات چیکر (پری ہک اسکرپٹ، لائف سائیکل ہک نہیں)
+3. **ورکر سروس** - ویب ویور UI اور 10 تلاش کے endpoints کے ساتھ پورٹ 37777 پر HTTP API، Bun کے ذریعے برتاؤ
+4. **SQLite ڈیٹا بیس** - سیشنز، مشاہدات، خلاصہ ذخیرہ کرتا ہے
+5. **mem-search مہارت** - بتدریج ظہور کے ساتھ قدرتی زبان کے سوالات
+6. **Chroma ویکٹر ڈیٹا بیس** - ہائبرڈ سیمانٹک + کلیدی لفظ تلاش ذہین تناسب کی بازیافت کے لیے
+
+تفصیلات کے لیے [تعمیر کا جائزہ](https://docs.claude-mem.ai/architecture/overview) دیکھیں۔
+
+---
+
+## MCP تلاش کے اوزار
+
+Claude-Mem ٹوکن-موثر **3-لیئر ورک فلو پیٹرن** کی پیروی کرتے ہوئے **4 MCP اوزار** کے ذریعے ذہین میموری تلاش فراہم کرتا ہے:
+
+**3-لیئر ورک فلو:**
+
+1. **`search`** - IDs کے ساتھ کمپیکٹ انڈیکس حاصل کریں (~50-100 ٹوکن/نتیجہ)
+2. **`timeline`** - دلچسپ نتائج کے ارد گرد زمانی تناسب حاصل کریں
+3. **`get_observations`** - فلٹر شدہ IDs کے لیے صرف مکمل تفصیلات حاصل کریں (~500-1,000 ٹوکن/نتیجہ)
+
+**یہ کیسے کام کرتا ہے:**
+- Claude آپ کی میموری میں تلاش کے لیے MCP اوزار استعمال کرتا ہے
+- نتائج کا انڈیکس حاصل کرنے کے لیے `search` سے شروع کریں
+- مخصوص مشاہدات کے ارد گرد کیا ہو رہا تھا دیکھنے کے لیے `timeline` استعمال کریں
+- متعلقہ IDs کے لیے مکمل تفصیلات حاصل کرنے کے لیے `get_observations` استعمال کریں
+- تفصیلات حاصل کرنے سے پہلے فلٹرنگ کے ذریعے **~10x ٹوکن کی بچت**
+
+**دستیاب MCP اوزار:**
+
+1. **`search`** - مکمل متن کی تلاش کے سوالات کے ساتھ میموری انڈیکس تلاش کریں، قسم/تاریخ/منصوبے کے لحاظ سے فلٹر کریں
+2. **`timeline`** - مخصوص مشاہدہ یا سوال کے ارد گرد زمانی تناسب حاصل کریں
+3. **`get_observations`** - IDs کے ذریعے مکمل مشاہدہ تفصیلات حاصل کریں (ہمیشہ متعدد IDs کو بیچ کریں)
+4. **`__IMPORTANT`** - ورک فلو دستاویزات (ہمیشہ Claude کو نظر آتی ہے)
+
+**استعمال کی مثال:**
+
+```typescript
+// مرحلہ 1: انڈیکس کے لیے تلاش کریں
+search(query="authentication bug", type="bugfix", limit=10)
+
+// مرحلہ 2: انڈیکس کا جائزہ لیں، متعلقہ IDs کی شناخت کریں (مثلاً، #123, #456)
+
+// مرحلہ 3: مکمل تفصیلات حاصل کریں
+get_observations(ids=[123, 456])
+```
+
+تفصیلی مثالوں کے لیے [تلاش کے اوزار گائیڈ](https://docs.claude-mem.ai/usage/search-tools) دیکھیں۔
+
+---
+
+## بیٹا خصوصیات
+
+Claude-Mem ایک **بیٹا چینل** فراہم کرتا ہے جس میں **Endless Mode** جیسی تجرباتی خصوصیات ہیں (بڑھی ہوئی سیشنز کے لیے حیاتی نقل میموری کی تعمیر)۔ http://localhost:37777 → Settings میں ویب ویور UI سے مستحکم اور بیٹا ورژن کے درمیان سوئچ کریں۔
+
+Endless Mode اور اسے کیسے آزمائیں اس کے بارے میں تفصیلات کے لیے **[بیٹا خصوصیات دستاویزات](https://docs.claude-mem.ai/beta-features)** دیکھیں۔
+
+---
+
+## نظام کی ضروریات
+
+- **Node.js**: 18.0.0 یا اس سے اوپر
+- **Claude Code**: پلگ ان سپورٹ کے ساتھ جدید ترین ورژن
+- **Bun**: JavaScript رن ٹائم اور پروسیس مینیجر (غیر موجود ہو تو خودکار طور پر انسٹال ہوگا)
+- **uv**: ویکٹر تلاش کے لیے Python پیکج مینیجر (غیر موجود ہو تو خودکار طور پر انسٹال ہوگا)
+- **SQLite 3**: مستقل اسٹوریج کے لیے (بنڈل شدہ)
+
+---
+
+## ترتیبات
+
+سیٹنگز `~/.claude-mem/settings.json` میں منظم ہیں (پہلی رن میں ڈیفالٹ کے ساتھ خودکار طور پر بنائی جاتی ہے)۔ AI ماڈل، ورکر پورٹ، ڈیٹا ڈائریکٹری، لاگ لیول اور تناسب انجیکشن سیٹنگز کو ترتیب دیں۔
+
+تمام دستیاب سیٹنگز اور مثالوں کے لیے **[ترتیبات گائیڈ](https://docs.claude-mem.ai/configuration)** دیکھیں۔
+
+---
+
+## ترقی
+
+تعمیر کی ہدایات، جانچ اور حصہ داری کے کام کے بہاؤ کے لیے **[ترقی گائیڈ](https://docs.claude-mem.ai/development)** دیکھیں۔
+
+---
+
+## مسائل کی تشخیص
+
+اگر مسائل کا سامنا ہو تو Claude کو مسئلہ بتائیں اور troubleshoot مہارت خودکار طور پر تشخیص دے گی اور حل فراہم کرے گی۔
+
+عام مسائل اور حل کے لیے **[مسائل کی تشخیص گائیڈ](https://docs.claude-mem.ai/troubleshooting)** دیکھیں۔
+
+---
+
+## خرابی کی رپورٹ
+
+خودکار جنریٹر کے ساتھ تفصیلی خرابی کی رپورٹ تیار کریں:
+
+```bash
+cd ~/.claude/plugins/marketplaces/thedotmack
+npm run bug-report
+```
+
+## حصہ داری
+
+حصہ داری کا خیر مقدم ہے! براہ کرم:
+
+1. رپوزیٹری کو فورک کریں
+2. ایک خصوصیت کی برانچ بنائیں
+3. ٹیسٹ کے ساتھ اپنی تبدیلیاں کریں
+4. دستاویزات کو اپڈیٹ کریں
+5. ایک Pull Request جمع کریں
+
+حصہ داری کے کام کے بہاؤ کے لیے [ترقی گائیڈ](https://docs.claude-mem.ai/development) دیکھیں۔
+
+---
+
+## لائسنس
+
+یہ منصوبہ **GNU Affero General Public License v3.0** (AGPL-3.0) کے تحت لائسنس ہے۔
+
+Copyright (C) 2025 Alex Newman (@thedotmack)۔ تمام حقوق محفوظ ہیں۔
+
+مکمل تفصیلات کے لیے [LICENSE](LICENSE) فائل دیکھیں۔
+
+**اس کا مطلب کیا ہے:**
+
+- آپ اس سافٹ ویئر کو آزادی سے استعمال، تبدیل اور تقسیم کر سکتے ہیں
+- اگر آپ اسے تبدیل کریں اور نیٹ ورک سرور میں نشر کریں تو آپ کو اپنا سورس کوڈ دستیاب کرنا ہوگا
+- ماخوذ کام بھی AGPL-3.0 کے تحت لائسنس ہونے چاہیں
+- اس سافٹ ویئر کے لیے کوئی وارنٹی نہیں
+
+**Ragtime کے بارے میں نوٹ**: `ragtime/` ڈائریکٹری الگ سے **PolyForm Noncommercial License 1.0.0** کے تحت لائسنس ہے۔ تفصیلات کے لیے [ragtime/LICENSE](ragtime/LICENSE) دیکھیں۔
+
+---
+
+## معاونت
+
+- **دستاویزات**: [docs/](docs/)
+- **مسائل**: [GitHub Issues](https://github.com/thedotmack/claude-mem/issues)
+- **رپوزیٹری**: [github.com/thedotmack/claude-mem](https://github.com/thedotmack/claude-mem)
+- **مصنف**: Alex Newman ([@thedotmack](https://github.com/thedotmack))
+
+---
+
+**Claude Agent SDK کے ساتھ بنایا گیا** | **Claude Code کے ذریعے طاقت ور** | **TypeScript کے ساتھ بنایا گیا**
+
+</section>

docs/i18n/README.vi.md

@@ -15,6 +15,7 @@
 
 <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> •
@@ -34,6 +35,7 @@
   <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> •
@@ -126,7 +128,7 @@ Khởi động lại Claude Code. Ngữ cảnh từ các phiên trước sẽ t
 
 ## Tài Liệu
 
-📚 **[Xem Tài Liệu Đầy Đủ](docs/)** - Duyệt tài liệu markdown trên GitHub
+📚 **[Xem Tài Liệu Đầy Đủ](https://docs.claude-mem.ai/)** - Duyệt trên trang web chính thức
 
 ### Bắt Đầu
 

docs/i18n/README.zh-tw.md

@@ -0,0 +1,311 @@
+🌐 這是自動翻譯。歡迎社群貢獻修正！
+
+---
+<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.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.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">為 <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="#快速開始">快速開始</a> •
+  <a href="#運作原理">運作原理</a> •
+  <a href="#mcp-搜尋工具">搜尋工具</a> •
+  <a href="#文件">文件</a> •
+  <a href="#設定">設定</a> •
+  <a href="#疑難排解">疑難排解</a> •
+  <a href="#授權條款">授權條款</a>
+</p>
+
+<p align="center">
+  Claude-Mem 透過自動擷取工具使用觀察、產生語意摘要並在未來的工作階段中提供使用，無縫保留跨工作階段的脈絡。這使 Claude 即使在工作階段結束或重新連線後，仍能維持對專案的知識連續性。
+</p>
+
+---
+
+## 快速開始
+
+在終端機中開啟新的 Claude Code 工作階段，並輸入以下指令：
+
+```
+> /plugin marketplace add thedotmack/claude-mem
+
+> /plugin install claude-mem
+```
+
+重新啟動 Claude Code。先前工作階段的脈絡將自動出現在新的工作階段中。
+
+**主要功能：**
+
+- 🧠 **持久記憶** - 脈絡跨工作階段保留
+- 📊 **漸進式揭露** - 具有 Token 成本可見性的分層記憶擷取
+- 🔍 **技能式搜尋** - 使用 mem-search 技能查詢專案歷史
+- 🖥️ **網頁檢視介面** - 在 http://localhost:37777 即時檢視記憶串流
+- 💻 **Claude Desktop 技能** - 從 Claude Desktop 對話中搜尋記憶
+- 🔒 **隱私控制** - 使用 `<private>` 標籤排除敏感內容的儲存
+- ⚙️ **脈絡設定** - 精細控制注入哪些脈絡
+- 🤖 **自動運作** - 無需手動介入
+- 🔗 **引用** - 使用 ID 參考過去的觀察（透過 http://localhost:37777/api/observation/{id} 存取，或在 http://localhost:37777 的網頁檢視器中檢視全部）
+- 🧪 **Beta 通道** - 透過版本切換試用 Endless Mode 等實驗性功能
+
+---
+
+## 文件
+
+📚 **[檢視完整文件](docs/)** - 在 GitHub 上瀏覽 Markdown 文件
+
+### 入門指南
+
+- **[安裝指南](https://docs.claude-mem.ai/installation)** - 快速開始與進階安裝
+- **[使用指南](https://docs.claude-mem.ai/usage/getting-started)** - Claude-Mem 如何自動運作
+- **[搜尋工具](https://docs.claude-mem.ai/usage/search-tools)** - 使用自然語言查詢專案歷史
+- **[Beta 功能](https://docs.claude-mem.ai/beta-features)** - 試用 Endless Mode 等實驗性功能
+
+### 最佳實務
+
+- **[脈絡工程](https://docs.claude-mem.ai/context-engineering)** - AI 代理脈絡最佳化原則
+- **[漸進式揭露](https://docs.claude-mem.ai/progressive-disclosure)** - Claude-Mem 脈絡啟動策略背後的理念
+
+### 架構
+
+- **[概覽](https://docs.claude-mem.ai/architecture/overview)** - 系統元件與資料流程
+- **[架構演進](https://docs.claude-mem.ai/architecture-evolution)** - 從 v3 到 v5 的旅程
+- **[Hooks 架構](https://docs.claude-mem.ai/hooks-architecture)** - Claude-Mem 如何使用生命週期掛鉤
+- **[Hooks 參考](https://docs.claude-mem.ai/architecture/hooks)** - 7 個掛鉤腳本說明
+- **[Worker 服務](https://docs.claude-mem.ai/architecture/worker-service)** - HTTP API 與 Bun 管理
+- **[資料庫](https://docs.claude-mem.ai/architecture/database)** - SQLite 結構描述與 FTS5 搜尋
+- **[搜尋架構](https://docs.claude-mem.ai/architecture/search-architecture)** - 使用 Chroma 向量資料庫的混合搜尋
+
+### 設定與開發
+
+- **[設定](https://docs.claude-mem.ai/configuration)** - 環境變數與設定
+- **[開發](https://docs.claude-mem.ai/development)** - 建置、測試、貢獻
+- **[疑難排解](https://docs.claude-mem.ai/troubleshooting)** - 常見問題與解決方案
+
+---
+
+## 運作原理
+
+**核心元件：**
+
+1. **5 個生命週期掛鉤** - SessionStart、UserPromptSubmit、PostToolUse、Stop、SessionEnd（6 個掛鉤腳本）
+2. **智慧安裝** - 快取的相依性檢查器（pre-hook 腳本，非生命週期掛鉤）
+3. **Worker 服務** - 連接埠 37777 上的 HTTP API，含網頁檢視介面與 10 個搜尋端點，由 Bun 管理
+4. **SQLite 資料庫** - 儲存工作階段、觀察、摘要
+5. **mem-search 技能** - 具有漸進式揭露的自然語言查詢
+6. **Chroma 向量資料庫** - 用於智慧脈絡擷取的混合語意 + 關鍵字搜尋
+
+詳情請參閱[架構概覽](https://docs.claude-mem.ai/architecture/overview)。
+
+---
+
+## MCP 搜尋工具
+
+Claude-Mem 透過遵循 Token 高效的 **3 層工作流程模式**，以 **4 個 MCP 工具**提供智慧記憶搜尋：
+
+**3 層工作流程：**
+
+1. **`search`** - 取得精簡索引與 ID（每筆結果約 50-100 tokens）
+2. **`timeline`** - 取得有趣結果周圍的時間脈絡
+3. **`get_observations`** - 僅為過濾後的 ID 擷取完整詳情（每筆結果約 500-1,000 tokens）
+
+**運作方式：**
+
+- Claude 使用 MCP 工具搜尋您的記憶
+- 從 `search` 開始取得結果索引
+- 使用 `timeline` 檢視特定觀察周圍發生的事情
+- 使用 `get_observations` 擷取相關 ID 的完整詳情
+- 透過在擷取詳情前過濾，**節省約 10 倍 token**
+
+**可用的 MCP 工具：**
+
+1. **`search`** - 使用全文查詢搜尋記憶索引，依類型/日期/專案過濾
+2. **`timeline`** - 取得特定觀察或查詢周圍的時間脈絡
+3. **`get_observations`** - 依 ID 擷取完整觀察詳情（批次處理多個 ID）
+4. **`__IMPORTANT`** - 工作流程文件（Claude 永遠可見）
+
+**使用範例：**
+
+```typescript
+// 步驟 1：搜尋索引
+search(query="authentication bug", type="bugfix", limit=10)
+
+// 步驟 2：檢閱索引，識別相關 ID（例如 #123、#456）
+
+// 步驟 3：擷取完整詳情
+get_observations(ids=[123, 456])
+```
+
+詳細範例請參閱[搜尋工具指南](https://docs.claude-mem.ai/usage/search-tools)。
+
+---
+
+## Beta 功能
+
+Claude-Mem 提供具有實驗性功能的 **Beta 通道**，例如 **Endless Mode**（用於延長工作階段的仿生記憶架構）。在 http://localhost:37777 → Settings 的網頁檢視介面中切換穩定版與 Beta 版。
+
+有關 Endless Mode 與如何試用的詳情，請參閱 **[Beta 功能文件](https://docs.claude-mem.ai/beta-features)**。
+
+---
+
+## 系統需求
+
+- **Node.js**：18.0.0 或更高版本
+- **Claude Code**：具有外掛支援的最新版本
+- **Bun**：JavaScript 執行環境與程序管理員（如缺少將自動安裝）
+- **uv**：用於向量搜尋的 Python 套件管理員（如缺少將自動安裝）
+- **SQLite 3**：用於持久儲存（已內建）
+
+---
+
+## 設定
+
+設定在 `~/.claude-mem/settings.json` 中管理（首次執行時自動以預設值建立）。設定 AI 模型、Worker 連接埠、資料目錄、日誌層級與脈絡注入設定。
+
+所有可用設定與範例請參閱 **[設定指南](https://docs.claude-mem.ai/configuration)**。
+
+---
+
+## 開發
+
+建置說明、測試與貢獻工作流程請參閱 **[開發指南](https://docs.claude-mem.ai/development)**。
+
+---
+
+## 疑難排解
+
+如遇問題，向 Claude 描述問題，troubleshoot 技能將自動診斷並提供修正。
+
+常見問題與解決方案請參閱 **[疑難排解指南](https://docs.claude-mem.ai/troubleshooting)**。
+
+---
+
+## 錯誤回報
+
+使用自動產生器建立完整的錯誤回報：
+
+```bash
+cd ~/.claude/plugins/marketplaces/thedotmack
+npm run bug-report
+```
+
+## 貢獻
+
+歡迎貢獻！請依照以下步驟：
+
+1. Fork 儲存庫
+2. 建立功能分支
+3. 加入測試並進行變更
+4. 更新文件
+5. 提交 Pull Request
+
+貢獻工作流程請參閱[開發指南](https://docs.claude-mem.ai/development)。
+
+---
+
+## 授權條款
+
+本專案採用 **GNU Affero 通用公共授權條款 v3.0**（AGPL-3.0）授權。
+
+Copyright (C) 2025 Alex Newman (@thedotmack). All rights reserved.
+
+完整詳情請參閱 [LICENSE](LICENSE) 檔案。
+
+**這代表什麼：**
+
+- 您可以自由使用、修改與散佈此軟體
+- 如果您修改並部署於網路伺服器上，您必須公開您的原始碼
+- 衍生作品也必須採用 AGPL-3.0 授權
+- 本軟體不提供任何擔保
+
+**關於 Ragtime 的說明**：`ragtime/` 目錄採用 **PolyForm Noncommercial License 1.0.0** 另行授權。詳情請參閱 [ragtime/LICENSE](ragtime/LICENSE)。
+
+---
+
+## 支援
+
+- **文件**：[docs/](docs/)
+- **Issues**：[GitHub Issues](https://github.com/thedotmack/claude-mem/issues)
+- **儲存庫**：[github.com/thedotmack/claude-mem](https://github.com/thedotmack/claude-mem)
+- **官方 X 帳號**：[@Claude_Memory](https://x.com/Claude_Memory)
+- **官方 Discord**：[加入 Discord](https://discord.com/invite/J4wttp9vDu)
+- **作者**：Alex Newman ([@thedotmack](https://github.com/thedotmack))
+
+---
+
+**使用 Claude Agent SDK 建置** | **由 Claude Code 驅動** | **以 TypeScript 開發**

docs/i18n/README.zh.md

@@ -15,6 +15,7 @@
 
 <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> •
@@ -34,6 +35,7 @@
   <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> •
@@ -126,7 +128,7 @@
 
 ## 文档
 
-📚 **[查看完整文档](docs/)** - 在 GitHub 上浏览 Markdown 文档
+📚 **[查看完整文档](https://docs.claude-mem.ai/)** - 在官方网站浏览
 
 ### 入门指南
 
@@ -212,7 +214,7 @@ Claude-Mem 通过 mem-search 技能提供智能搜索,当您询问过去的工
 
 Claude-Mem 提供**测试版渠道**,包含实验性功能,如**无尽模式**(用于扩展会话的仿生记忆架构)。从 Web 查看器界面 http://localhost:37777 → 设置 切换稳定版和测试版。
 
-详见**[测试版功能文档](https://docs.claude-mem.ai/beta-features)**了解无尽模式的详细信息和试用方法。
+详见 **[测试版功能文档](https://docs.claude-mem.ai/beta-features)** 了解无尽模式的详细信息和试用方法。
 
 ---
 
@@ -230,13 +232,13 @@ Claude-Mem 提供**测试版渠道**,包含实验性功能,如**无尽模式**(
 
 设置在 `~/.claude-mem/settings.json` 中管理(首次运行时自动创建默认设置)。可配置 AI 模型、worker 端口、数据目录、日志级别和上下文注入设置。
 
-详见**[配置指南](https://docs.claude-mem.ai/configuration)**了解所有可用设置和示例。
+详见 **[配置指南](https://docs.claude-mem.ai/configuration)** 了解所有可用设置和示例。
 
 ---
 
 ## 开发
 
-详见**[开发指南](https://docs.claude-mem.ai/development)**了解构建说明、测试和贡献工作流程。
+详见 **[开发指南](https://docs.claude-mem.ai/development)** 了解构建说明、测试和贡献工作流程。
 
 ---
 
@@ -244,7 +246,7 @@ Claude-Mem 提供**测试版渠道**,包含实验性功能,如**无尽模式**(
 
 如果遇到问题,向 Claude 描述问题,troubleshoot 技能将自动诊断并提供修复方案。
 
-详见**[故障排除指南](https://docs.claude-mem.ai/troubleshooting)**了解常见问题和解决方案。
+详见 **[故障排除指南](https://docs.claude-mem.ai/troubleshooting)** 了解常见问题和解决方案。
 
 ---
 
@@ -301,4 +303,4 @@ Copyright (C) 2025 Alex Newman (@thedotmack)。保留所有权利。
 
 **使用 Claude Agent SDK 构建** | **由 Claude Code 驱动** | **使用 TypeScript 制作**
 
----
+---

docs/public/configuration.mdx

@@ -26,7 +26,7 @@ Settings are managed in `~/.claude-mem/settings.json`. The file is auto-created
 | Setting                       | Default                         | Description                           |
 |-------------------------------|---------------------------------|---------------------------------------|
 | `CLAUDE_MEM_GEMINI_API_KEY`   | —                               | Gemini API key ([get free key](https://aistudio.google.com/app/apikey)) |
-| `CLAUDE_MEM_GEMINI_MODEL`     | `gemini-2.5-flash-lite`          | Gemini model: `gemini-2.5-flash-lite`, `gemini-2.5-flash`, `gemini-3-flash` |
+| `CLAUDE_MEM_GEMINI_MODEL`     | `gemini-2.5-flash-lite`          | Gemini model: `gemini-2.5-flash-lite`, `gemini-2.5-flash`, `gemini-3-flash-preview` |
 
 See [Gemini Provider](usage/gemini-provider) for detailed configuration and free tier information.
 

docs/public/cursor/gemini-setup.mdx

@@ -103,7 +103,7 @@ Open http://localhost:37777 to see the memory viewer.
 |-------|---------------|-------|
 | `gemini-2.5-flash-lite` | 10 (4,000 with billing) | **Default.** Fastest, highest free tier RPM |
 | `gemini-2.5-flash` | 5 (1,000 with billing) | Higher capability |
-| `gemini-3-flash` | 5 (1,000 with billing) | Latest model |
+| `gemini-3-flash-preview` | 5 (1,000 with billing) | Latest model |
 
 To change the model, update your settings:
 

docs/public/docs.json

@@ -73,7 +73,8 @@
           "modes",
           "development",
           "troubleshooting",
-          "platform-integration"
+          "platform-integration",
+          "openclaw-integration"
         ]
       },
       {

docs/public/modes.mdx

@@ -65,6 +65,7 @@ Inherits all behavior from Code Mode but instructs Claude to generate **all** me
 | **Hindi** | `code--hi` | हिन्दी |
 | **Hungarian** | `code--hu` | Magyar |
 | **Indonesian** | `code--id` | Bahasa Indonesia |
+| **Urdu** | `code--ur` | اردو |
 | **Italian** | `code--it` | Italiano |
 | **Japanese** | `code--ja` | 日本語 |
 | **Korean** | `code--ko` | 한국어 |

docs/public/openclaw-integration.mdx

@@ -0,0 +1,362 @@
+---
+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
+
+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/usage/gemini-provider.mdx

@@ -39,7 +39,7 @@ Claude-mem supports Google's Gemini API as an alternative to the Claude Agent SD
 |---------|--------|---------|-------------|
 | `CLAUDE_MEM_PROVIDER` | `claude`, `gemini` | `claude` | AI provider for observation extraction |
 | `CLAUDE_MEM_GEMINI_API_KEY` | string | — | Your Gemini API key |
-| `CLAUDE_MEM_GEMINI_MODEL` | `gemini-2.5-flash-lite`, `gemini-2.5-flash`, `gemini-3-flash` | `gemini-2.5-flash-lite` | Gemini model to use |
+| `CLAUDE_MEM_GEMINI_MODEL` | `gemini-2.5-flash-lite`, `gemini-2.5-flash`, `gemini-3-flash-preview` | `gemini-2.5-flash-lite` | Gemini model to use |
 | `CLAUDE_MEM_GEMINI_BILLING_ENABLED` | `true`, `false` | `false` | Skip rate limiting if billing is enabled on Google Cloud |
 
 ### Using the Settings UI
@@ -79,7 +79,7 @@ The settings file takes precedence over the environment variable.
 |-------|--------------|-------|
 | `gemini-2.5-flash-lite` | 10 | Default, recommended for free tier (highest RPM) |
 | `gemini-2.5-flash` | 5 | Higher capability, lower rate limit |
-| `gemini-3-flash` | 5 | Latest model, lower rate limit |
+| `gemini-3-flash-preview` | 5 | Latest model, lower rate limit |
 
 ## Provider Switching
 
@@ -139,7 +139,7 @@ Google has two rate limit tiers for free usage:
 |-------|-----|-----|
 | gemini-2.5-flash-lite | 10 | 250K |
 | gemini-2.5-flash | 5 | 250K |
-| gemini-3-flash | 5 | 250K |
+| gemini-3-flash-preview | 5 | 250K |
 
 Claude-mem enforces these limits automatically with built-in delays between requests. Processing may be slower but stays within limits.
 
@@ -149,7 +149,7 @@ Claude-mem enforces these limits automatically with built-in delays between requ
 |-------|-----|-----|
 | gemini-2.5-flash-lite | 4,000 | 4M |
 | gemini-2.5-flash | 1,000 | 1M |
-| gemini-3-flash | 1,000 | 1M |
+| gemini-3-flash-preview | 1,000 | 1M |
 
 <Tip>
 **Recommended**: Enable billing on your Google Cloud project to unlock much higher rate limits. You won't be charged unless you exceed the generous free quota. This allows claude-mem to process observations instantly instead of waiting between requests.

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,418 @@
+# Claude-Mem OpenClaw Plugin — Setup Guide
+
+This guide walks through setting up the claude-mem plugin on an OpenClaw gateway from scratch. Follow every step in order. 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.
+
+## 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,49 @@
+{
+  "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": "integration",
+  "version": "1.0.0",
+  "author": "thedotmack",
+  "homepage": "https://claude-mem.com",
+  "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"
+          }
+        }
+      }
+    }
+  }
+}

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/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.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.includes("Enabled: yes"));
+      assert.ok(result.includes("Channel: telegram"));
+      assert.ok(result.includes("Target: 123"));
+      assert.ok(result.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.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.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.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.includes("Status: ok"));
+    assert.ok(result.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.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/src/index.ts

@@ -0,0 +1,737 @@
+import { writeFile } from "fs/promises";
+import { join } from "path";
+
+// Minimal type declarations for the OpenClaw Plugin SDK.
+// These match the real OpenClawPluginApi provided by the gateway at runtime.
+// See: https://docs.openclaw.ai/plugin
+
+interface PluginLogger {
+  debug?: (message: string) => void;
+  info: (message: string) => void;
+  warn: (message: string) => void;
+  error: (message: string) => void;
+}
+
+interface PluginServiceContext {
+  config: Record<string, unknown>;
+  workspaceDir?: string;
+  stateDir: string;
+  logger: PluginLogger;
+}
+
+interface PluginCommandContext {
+  senderId?: string;
+  channel: string;
+  isAuthorizedSender: boolean;
+  args?: string;
+  commandBody: string;
+  config: Record<string, unknown>;
+}
+
+type PluginCommandResult = string | { text: string } | { text: string; format?: string };
+
+// OpenClaw event types for agent lifecycle
+interface BeforeAgentStartEvent {
+  prompt?: string;
+}
+
+interface ToolResultPersistEvent {
+  toolName?: string;
+  params?: Record<string, unknown>;
+  message?: {
+    content?: Array<{ type: string; text?: string }>;
+  };
+}
+
+interface AgentEndEvent {
+  messages?: Array<{
+    role: string;
+    content: string | Array<{ type: string; text?: string }>;
+  }>;
+}
+
+interface SessionStartEvent {
+  sessionId: string;
+  resumedFrom?: string;
+}
+
+interface AfterCompactionEvent {
+  messageCount: number;
+  tokenCount?: number;
+  compactedCount: number;
+}
+
+interface SessionEndEvent {
+  sessionId: string;
+  messageCount: number;
+  durationMs?: number;
+}
+
+interface EventContext {
+  sessionKey?: string;
+  workspaceDir?: string;
+  agentId?: string;
+}
+
+type EventCallback<T> = (event: T, ctx: EventContext) => void | Promise<void>;
+
+interface OpenClawPluginApi {
+  id: string;
+  name: string;
+  version?: string;
+  source: string;
+  config: Record<string, unknown>;
+  pluginConfig?: Record<string, unknown>;
+  logger: PluginLogger;
+  registerService: (service: {
+    id: string;
+    start: (ctx: PluginServiceContext) => void | Promise<void>;
+    stop?: (ctx: PluginServiceContext) => void | Promise<void>;
+  }) => void;
+  registerCommand: (command: {
+    name: string;
+    description: string;
+    acceptsArgs?: boolean;
+    requireAuth?: boolean;
+    handler: (ctx: PluginCommandContext) => PluginCommandResult | Promise<PluginCommandResult>;
+  }) => void;
+  on: ((event: "before_agent_start", callback: EventCallback<BeforeAgentStartEvent>) => void) &
+      ((event: "tool_result_persist", callback: EventCallback<ToolResultPersistEvent>) => void) &
+      ((event: "agent_end", callback: EventCallback<AgentEndEvent>) => void) &
+      ((event: "session_start", callback: EventCallback<SessionStartEvent>) => void) &
+      ((event: "session_end", callback: EventCallback<SessionEndEvent>) => void) &
+      ((event: "after_compaction", callback: EventCallback<AfterCompactionEvent>) => void) &
+      ((event: "gateway_start", callback: EventCallback<Record<string, never>>) => void);
+  runtime: {
+    channel: Record<string, Record<string, (...args: any[]) => Promise<any>>>;
+  };
+}
+
+// ============================================================================
+// SSE Observation Feed Types
+// ============================================================================
+
+interface ObservationSSEPayload {
+  id: number;
+  memory_session_id: string;
+  session_id: string;
+  type: string;
+  title: string | null;
+  subtitle: string | null;
+  text: string | null;
+  narrative: string | null;
+  facts: string | null;
+  concepts: string | null;
+  files_read: string | null;
+  files_modified: string | null;
+  project: string | null;
+  prompt_number: number;
+  created_at_epoch: number;
+}
+
+interface SSENewObservationEvent {
+  type: "new_observation";
+  observation: ObservationSSEPayload;
+  timestamp: number;
+}
+
+type ConnectionState = "disconnected" | "connected" | "reconnecting";
+
+// ============================================================================
+// Plugin Configuration
+// ============================================================================
+
+interface ClaudeMemPluginConfig {
+  syncMemoryFile?: boolean;
+  project?: string;
+  workerPort?: number;
+  observationFeed?: {
+    enabled?: boolean;
+    channel?: string;
+    to?: string;
+  };
+}
+
+// ============================================================================
+// Constants
+// ============================================================================
+
+const MAX_SSE_BUFFER_SIZE = 1024 * 1024; // 1MB
+const DEFAULT_WORKER_PORT = 37777;
+const TOOL_RESULT_MAX_LENGTH = 1000;
+
+// Agent emoji map for observation feed messages.
+// When creating a new OpenClaw agent, add its agentId and emoji here.
+const AGENT_EMOJI_MAP: Record<string, string> = {
+  "main":          "🦞",
+  "openclaw":      "🦞",
+  "devops":        "🔧",
+  "architect":     "📐",
+  "researcher":    "🔍",
+  "code-reviewer": "🔎",
+  "coder":         "💻",
+  "tester":        "🧪",
+  "debugger":      "🐛",
+  "opsec":         "🛡️",
+  "cloudfarm":     "☁️",
+  "extractor":     "📦",
+};
+
+// Project prefixes that indicate Claude Code sessions (not OpenClaw agents)
+const CLAUDE_CODE_EMOJI = "⌨️";
+const OPENCLAW_DEFAULT_EMOJI = "🦀";
+
+function getSourceLabel(project: string | null | undefined): string {
+  if (!project) return OPENCLAW_DEFAULT_EMOJI;
+  // OpenClaw agent projects are formatted as "openclaw-<agentId>"
+  if (project.startsWith("openclaw-")) {
+    const agentId = project.slice("openclaw-".length);
+    const emoji = AGENT_EMOJI_MAP[agentId] || OPENCLAW_DEFAULT_EMOJI;
+    return `${emoji} ${agentId}`;
+  }
+  // OpenClaw project without agent suffix
+  if (project === "openclaw") {
+    return `🦞 openclaw`;
+  }
+  // Everything else is from Claude Code (project = working directory name)
+  const emoji = CLAUDE_CODE_EMOJI;
+  return `${emoji} ${project}`;
+}
+
+// ============================================================================
+// Worker HTTP Client
+// ============================================================================
+
+function workerBaseUrl(port: number): string {
+  return `http://127.0.0.1:${port}`;
+}
+
+async function workerPost(
+  port: number,
+  path: string,
+  body: Record<string, unknown>,
+  logger: PluginLogger
+): Promise<Record<string, unknown> | null> {
+  try {
+    const response = await fetch(`${workerBaseUrl(port)}${path}`, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify(body),
+    });
+    if (!response.ok) {
+      logger.warn(`[claude-mem] Worker POST ${path} returned ${response.status}`);
+      return null;
+    }
+    return (await response.json()) as Record<string, unknown>;
+  } catch (error: unknown) {
+    const message = error instanceof Error ? error.message : String(error);
+    logger.warn(`[claude-mem] Worker POST ${path} failed: ${message}`);
+    return null;
+  }
+}
+
+function workerPostFireAndForget(
+  port: number,
+  path: string,
+  body: Record<string, unknown>,
+  logger: PluginLogger
+): void {
+  fetch(`${workerBaseUrl(port)}${path}`, {
+    method: "POST",
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify(body),
+  }).catch((error: unknown) => {
+    const message = error instanceof Error ? error.message : String(error);
+    logger.warn(`[claude-mem] Worker POST ${path} failed: ${message}`);
+  });
+}
+
+async function workerGetText(
+  port: number,
+  path: string,
+  logger: PluginLogger
+): Promise<string | null> {
+  try {
+    const response = await fetch(`${workerBaseUrl(port)}${path}`);
+    if (!response.ok) {
+      logger.warn(`[claude-mem] Worker GET ${path} returned ${response.status}`);
+      return null;
+    }
+    return await response.text();
+  } catch (error: unknown) {
+    const message = error instanceof Error ? error.message : String(error);
+    logger.warn(`[claude-mem] Worker GET ${path} failed: ${message}`);
+    return null;
+  }
+}
+
+// ============================================================================
+// SSE Observation Feed
+// ============================================================================
+
+function formatObservationMessage(observation: ObservationSSEPayload): string {
+  const title = observation.title || "Untitled";
+  const source = getSourceLabel(observation.project);
+  let message = `${source}\n**${title}**`;
+  if (observation.subtitle) {
+    message += `\n${observation.subtitle}`;
+  }
+  return message;
+}
+
+// Explicit mapping from channel name to [runtime namespace key, send function name].
+// These match the PluginRuntime.channel structure in the OpenClaw SDK.
+const CHANNEL_SEND_MAP: Record<string, { namespace: string; functionName: string }> = {
+  telegram: { namespace: "telegram", functionName: "sendMessageTelegram" },
+  whatsapp: { namespace: "whatsapp", functionName: "sendMessageWhatsApp" },
+  discord: { namespace: "discord", functionName: "sendMessageDiscord" },
+  slack: { namespace: "slack", functionName: "sendMessageSlack" },
+  signal: { namespace: "signal", functionName: "sendMessageSignal" },
+  imessage: { namespace: "imessage", functionName: "sendMessageIMessage" },
+  line: { namespace: "line", functionName: "sendMessageLine" },
+};
+
+function sendToChannel(
+  api: OpenClawPluginApi,
+  channel: string,
+  to: string,
+  text: string
+): Promise<void> {
+  const mapping = CHANNEL_SEND_MAP[channel];
+  if (!mapping) {
+    api.logger.warn(`[claude-mem] Unsupported channel type: ${channel}`);
+    return Promise.resolve();
+  }
+
+  const channelApi = api.runtime.channel[mapping.namespace];
+  if (!channelApi) {
+    api.logger.warn(`[claude-mem] Channel "${channel}" not available in runtime`);
+    return Promise.resolve();
+  }
+
+  const senderFunction = channelApi[mapping.functionName];
+  if (!senderFunction) {
+    api.logger.warn(`[claude-mem] Channel "${channel}" has no ${mapping.functionName} function`);
+    return Promise.resolve();
+  }
+
+  // WhatsApp requires a third options argument with { verbose: boolean }
+  const args: unknown[] = channel === "whatsapp"
+    ? [to, text, { verbose: false }]
+    : [to, text];
+
+  return senderFunction(...args).catch((error: unknown) => {
+    const message = error instanceof Error ? error.message : String(error);
+    api.logger.error(`[claude-mem] Failed to send to ${channel}: ${message}`);
+  });
+}
+
+async function connectToSSEStream(
+  api: OpenClawPluginApi,
+  port: number,
+  channel: string,
+  to: string,
+  abortController: AbortController,
+  setConnectionState: (state: ConnectionState) => void
+): Promise<void> {
+  let backoffMs = 1000;
+  const maxBackoffMs = 30000;
+
+  while (!abortController.signal.aborted) {
+    try {
+      setConnectionState("reconnecting");
+      api.logger.info(`[claude-mem] Connecting to SSE stream at ${workerBaseUrl(port)}/stream`);
+
+      const response = await fetch(`${workerBaseUrl(port)}/stream`, {
+        signal: abortController.signal,
+        headers: { Accept: "text/event-stream" },
+      });
+
+      if (!response.ok) {
+        throw new Error(`SSE stream returned HTTP ${response.status}`);
+      }
+
+      if (!response.body) {
+        throw new Error("SSE stream response has no body");
+      }
+
+      setConnectionState("connected");
+      backoffMs = 1000;
+      api.logger.info("[claude-mem] Connected to SSE stream");
+
+      const reader = response.body.getReader();
+      const decoder = new TextDecoder();
+      let buffer = "";
+
+      while (true) {
+        const { done, value } = await reader.read();
+        if (done) break;
+
+        buffer += decoder.decode(value, { stream: true });
+
+        if (buffer.length > MAX_SSE_BUFFER_SIZE) {
+          api.logger.warn("[claude-mem] SSE buffer overflow, clearing buffer");
+          buffer = "";
+        }
+
+        const frames = buffer.split("\n\n");
+        buffer = frames.pop() || "";
+
+        for (const frame of frames) {
+          // SSE spec: concatenate all data: lines with \n
+          const dataLines = frame
+            .split("\n")
+            .filter((line) => line.startsWith("data:"))
+            .map((line) => line.slice(5).trim());
+          if (dataLines.length === 0) continue;
+
+          const jsonStr = dataLines.join("\n");
+          if (!jsonStr) continue;
+
+          try {
+            const parsed = JSON.parse(jsonStr);
+            if (parsed.type === "new_observation" && parsed.observation) {
+              const event = parsed as SSENewObservationEvent;
+              const message = formatObservationMessage(event.observation);
+              await sendToChannel(api, channel, to, message);
+            }
+          } catch (parseError: unknown) {
+            const errorMessage = parseError instanceof Error ? parseError.message : String(parseError);
+            api.logger.warn(`[claude-mem] Failed to parse SSE frame: ${errorMessage}`);
+          }
+        }
+      }
+    } catch (error: unknown) {
+      if (abortController.signal.aborted) {
+        break;
+      }
+      setConnectionState("reconnecting");
+      const errorMessage = error instanceof Error ? error.message : String(error);
+      api.logger.warn(`[claude-mem] SSE stream error: ${errorMessage}. Reconnecting in ${backoffMs / 1000}s`);
+    }
+
+    if (abortController.signal.aborted) break;
+
+    await new Promise((resolve) => setTimeout(resolve, backoffMs));
+    backoffMs = Math.min(backoffMs * 2, maxBackoffMs);
+  }
+
+  setConnectionState("disconnected");
+}
+
+// ============================================================================
+// Plugin Entry Point
+// ============================================================================
+
+export default function claudeMemPlugin(api: OpenClawPluginApi): void {
+  const userConfig = (api.pluginConfig || {}) as ClaudeMemPluginConfig;
+  const workerPort = userConfig.workerPort || DEFAULT_WORKER_PORT;
+  const baseProjectName = userConfig.project || "openclaw";
+
+  function getProjectName(ctx: EventContext): string {
+    if (ctx.agentId) {
+      return `openclaw-${ctx.agentId}`;
+    }
+    return baseProjectName;
+  }
+
+  // ------------------------------------------------------------------
+  // Session tracking for observation I/O
+  // ------------------------------------------------------------------
+  const sessionIds = new Map<string, string>();
+  const workspaceDirsBySessionKey = new Map<string, string>();
+  const syncMemoryFile = userConfig.syncMemoryFile !== false; // default true
+
+  function getContentSessionId(sessionKey?: string): string {
+    const key = sessionKey || "default";
+    if (!sessionIds.has(key)) {
+      sessionIds.set(key, `openclaw-${key}-${Date.now()}`);
+    }
+    return sessionIds.get(key)!;
+  }
+
+  async function syncMemoryToWorkspace(workspaceDir: string): Promise<void> {
+    const contextText = await workerGetText(
+      workerPort,
+      `/api/context/inject?projects=${encodeURIComponent(baseProjectName)}`,
+      api.logger
+    );
+    if (contextText && contextText.trim().length > 0) {
+      try {
+        await writeFile(join(workspaceDir, "MEMORY.md"), contextText, "utf-8");
+        api.logger.info(`[claude-mem] MEMORY.md synced to ${workspaceDir}`);
+      } catch (writeError: unknown) {
+        const msg = writeError instanceof Error ? writeError.message : String(writeError);
+        api.logger.warn(`[claude-mem] Failed to write MEMORY.md: ${msg}`);
+      }
+    }
+  }
+
+  // ------------------------------------------------------------------
+  // Event: session_start — init claude-mem session (fires on /new, /reset)
+  // ------------------------------------------------------------------
+  api.on("session_start", async (_event, ctx) => {
+    const contentSessionId = getContentSessionId(ctx.sessionKey);
+
+    await workerPost(workerPort, "/api/sessions/init", {
+      contentSessionId,
+      project: getProjectName(ctx),
+      prompt: "",
+    }, api.logger);
+
+    api.logger.info(`[claude-mem] Session initialized: ${contentSessionId}`);
+  });
+
+  // ------------------------------------------------------------------
+  // Event: after_compaction — re-init session after context compaction
+  // ------------------------------------------------------------------
+  api.on("after_compaction", async (_event, ctx) => {
+    const contentSessionId = getContentSessionId(ctx.sessionKey);
+
+    await workerPost(workerPort, "/api/sessions/init", {
+      contentSessionId,
+      project: getProjectName(ctx),
+      prompt: "",
+    }, api.logger);
+
+    api.logger.info(`[claude-mem] Session re-initialized after compaction: ${contentSessionId}`);
+  });
+
+  // ------------------------------------------------------------------
+  // Event: before_agent_start — init session + sync MEMORY.md + track workspace
+  // ------------------------------------------------------------------
+  api.on("before_agent_start", async (_event, ctx) => {
+    // Track workspace dir so tool_result_persist can sync MEMORY.md later
+    if (ctx.workspaceDir) {
+      workspaceDirsBySessionKey.set(ctx.sessionKey || "default", ctx.workspaceDir);
+    }
+
+    // Initialize session in the worker so observations are not skipped
+    // (the privacy check requires a stored user prompt to exist)
+    const contentSessionId = getContentSessionId(ctx.sessionKey);
+    await workerPost(workerPort, "/api/sessions/init", {
+      contentSessionId,
+      project: getProjectName(ctx),
+      prompt: ctx.sessionKey || "agent run",
+    }, api.logger);
+
+    // Sync MEMORY.md before agent runs (provides context to agent)
+    if (syncMemoryFile && ctx.workspaceDir) {
+      await syncMemoryToWorkspace(ctx.workspaceDir);
+    }
+  });
+
+  // ------------------------------------------------------------------
+  // Event: tool_result_persist — record tool observations + sync MEMORY.md
+  // ------------------------------------------------------------------
+  api.on("tool_result_persist", (event, ctx) => {
+    api.logger.info(`[claude-mem] tool_result_persist fired: tool=${event.toolName ?? "unknown"} agent=${ctx.agentId ?? "none"} session=${ctx.sessionKey ?? "none"}`);
+    const toolName = event.toolName;
+    if (!toolName || toolName.startsWith("memory_")) return;
+
+    const contentSessionId = getContentSessionId(ctx.sessionKey);
+
+    // Extract result text from message content
+    let toolResponseText = "";
+    const content = event.message?.content;
+    if (Array.isArray(content)) {
+      const textBlock = content.find(
+        (block) => block.type === "tool_result" || block.type === "text"
+      );
+      if (textBlock && "text" in textBlock) {
+        toolResponseText = String(textBlock.text).slice(0, TOOL_RESULT_MAX_LENGTH);
+      }
+    }
+
+    // Fire-and-forget: send observation + sync MEMORY.md in parallel
+    workerPostFireAndForget(workerPort, "/api/sessions/observations", {
+      contentSessionId,
+      tool_name: toolName,
+      tool_input: event.params || {},
+      tool_response: toolResponseText,
+      cwd: "",
+    }, api.logger);
+
+    const workspaceDir = ctx.workspaceDir || workspaceDirsBySessionKey.get(ctx.sessionKey || "default");
+    if (syncMemoryFile && workspaceDir) {
+      syncMemoryToWorkspace(workspaceDir);
+    }
+  });
+
+  // ------------------------------------------------------------------
+  // Event: agent_end — summarize and complete session
+  // ------------------------------------------------------------------
+  api.on("agent_end", async (event, ctx) => {
+    const contentSessionId = getContentSessionId(ctx.sessionKey);
+
+    // Extract last assistant message for summarization
+    let lastAssistantMessage = "";
+    if (Array.isArray(event.messages)) {
+      for (let i = event.messages.length - 1; i >= 0; i--) {
+        const message = event.messages[i];
+        if (message?.role === "assistant") {
+          if (typeof message.content === "string") {
+            lastAssistantMessage = message.content;
+          } else if (Array.isArray(message.content)) {
+            lastAssistantMessage = message.content
+              .filter((block) => block.type === "text")
+              .map((block) => block.text || "")
+              .join("\n");
+          }
+          break;
+        }
+      }
+    }
+
+    // Await summarize so the worker receives it before complete.
+    // This also gives in-flight tool_result_persist observations time to arrive
+    // (they use fire-and-forget and may still be in transit).
+    await workerPost(workerPort, "/api/sessions/summarize", {
+      contentSessionId,
+      last_assistant_message: lastAssistantMessage,
+    }, api.logger);
+
+    workerPostFireAndForget(workerPort, "/api/sessions/complete", {
+      contentSessionId,
+    }, api.logger);
+  });
+
+  // ------------------------------------------------------------------
+  // Event: session_end — clean up session tracking to prevent unbounded growth
+  // ------------------------------------------------------------------
+  api.on("session_end", async (_event, ctx) => {
+    const key = ctx.sessionKey || "default";
+    sessionIds.delete(key);
+    workspaceDirsBySessionKey.delete(key);
+  });
+
+  // ------------------------------------------------------------------
+  // Event: gateway_start — clear session tracking for fresh start
+  // ------------------------------------------------------------------
+  api.on("gateway_start", async () => {
+    workspaceDirsBySessionKey.clear();
+    sessionIds.clear();
+    api.logger.info("[claude-mem] Gateway started — session tracking reset");
+  });
+
+  // ------------------------------------------------------------------
+  // Service: SSE observation feed → messaging channels
+  // ------------------------------------------------------------------
+  let sseAbortController: AbortController | null = null;
+  let connectionState: ConnectionState = "disconnected";
+  let connectionPromise: Promise<void> | null = null;
+
+  api.registerService({
+    id: "claude-mem-observation-feed",
+    start: async (_ctx) => {
+      if (sseAbortController) {
+        sseAbortController.abort();
+        if (connectionPromise) {
+          await connectionPromise;
+          connectionPromise = null;
+        }
+      }
+
+      const feedConfig = userConfig.observationFeed;
+
+      if (!feedConfig?.enabled) {
+        api.logger.info("[claude-mem] Observation feed disabled");
+        return;
+      }
+
+      if (!feedConfig.channel || !feedConfig.to) {
+        api.logger.warn("[claude-mem] Observation feed misconfigured — channel or target missing");
+        return;
+      }
+
+      api.logger.info(`[claude-mem] Observation feed starting — channel: ${feedConfig.channel}, target: ${feedConfig.to}`);
+
+      sseAbortController = new AbortController();
+      connectionPromise = connectToSSEStream(
+        api,
+        workerPort,
+        feedConfig.channel,
+        feedConfig.to,
+        sseAbortController,
+        (state) => { connectionState = state; }
+      );
+    },
+    stop: async (_ctx) => {
+      if (sseAbortController) {
+        sseAbortController.abort();
+        sseAbortController = null;
+      }
+      if (connectionPromise) {
+        await connectionPromise;
+        connectionPromise = null;
+      }
+      connectionState = "disconnected";
+      api.logger.info("[claude-mem] Observation feed stopped — SSE connection closed");
+    },
+  });
+
+  // ------------------------------------------------------------------
+  // Command: /claude-mem-feed — status & toggle
+  // ------------------------------------------------------------------
+  api.registerCommand({
+    name: "claude-mem-feed",
+    description: "Show or toggle Claude-Mem observation feed status",
+    acceptsArgs: true,
+    handler: async (ctx) => {
+      const feedConfig = userConfig.observationFeed;
+
+      if (!feedConfig) {
+        return "Observation feed not configured. Add observationFeed to your plugin config.";
+      }
+
+      const arg = ctx.args?.trim();
+
+      if (arg === "on") {
+        api.logger.info("[claude-mem] Feed enable requested via command");
+        return "Feed enable requested. Update observationFeed.enabled in your plugin config to persist.";
+      }
+
+      if (arg === "off") {
+        api.logger.info("[claude-mem] Feed disable requested via command");
+        return "Feed disable requested. Update observationFeed.enabled in your plugin config to persist.";
+      }
+
+      return [
+        "Claude-Mem Observation Feed",
+        `Enabled: ${feedConfig.enabled ? "yes" : "no"}`,
+        `Channel: ${feedConfig.channel || "not set"}`,
+        `Target: ${feedConfig.to || "not set"}`,
+        `Connection: ${connectionState}`,
+      ].join("\n");
+    },
+  });
+
+  // ------------------------------------------------------------------
+  // Command: /claude-mem-status — worker health check
+  // ------------------------------------------------------------------
+  api.registerCommand({
+    name: "claude-mem-status",
+    description: "Check Claude-Mem worker health and session status",
+    handler: async () => {
+      const healthText = await workerGetText(workerPort, "/api/health", api.logger);
+      if (!healthText) {
+        return `Claude-Mem worker unreachable at port ${workerPort}`;
+      }
+
+      try {
+        const health = JSON.parse(healthText);
+        return [
+          "Claude-Mem Worker Status",
+          `Status: ${health.status || "unknown"}`,
+          `Port: ${workerPort}`,
+          `Active sessions: ${sessionIds.size}`,
+          `Observation feed: ${connectionState}`,
+        ].join("\n");
+      } catch {
+        return `Claude-Mem worker responded but returned unexpected data`;
+      }
+    },
+  });
+
+  api.logger.info(`[claude-mem] OpenClaw plugin loaded — v1.0.0 (worker: 127.0.0.1:${workerPort})`);
+}

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.0.16",
+  "version": "10.0.2",
   "description": "Memory compression system for Claude Code - persist context across sessions",
   "keywords": [
     "claude",
@@ -66,7 +66,7 @@
     "claude-md:regenerate": "bun scripts/regenerate-claude-md.ts",
     "claude-md:dry-run": "bun scripts/regenerate-claude-md.ts --dry-run",
     "translate-readme": "bun scripts/translate-readme/cli.ts -v -o docs/i18n README.md",
-    "translate:tier1": "npm run translate-readme -- zh ja pt-br ko es de fr",
+    "translate:tier1": "npm run translate-readme -- zh zh-tw ja pt-br ko es de fr",
     "translate:tier2": "npm run translate-readme -- he ar ru pl cs nl tr uk",
     "translate:tier3": "npm run translate-readme -- vi id th hi bn ro sv",
     "translate:tier4": "npm run translate-readme -- it el hu fi da no",
@@ -99,6 +99,7 @@
     "@anthropic-ai/claude-agent-sdk": "^0.1.76",
     "@modelcontextprotocol/sdk": "^1.25.1",
     "ansi-to-html": "^0.7.2",
+    "dompurify": "^3.3.1",
     "express": "^4.18.2",
     "glob": "^11.0.3",
     "handlebars": "^4.7.8",
@@ -109,6 +110,7 @@
   },
   "devDependencies": {
     "@types/cors": "^2.8.19",
+    "@types/dompurify": "^3.0.5",
     "@types/express": "^4.17.21",
     "@types/node": "^20.0.0",
     "@types/react": "^18.3.5",

plugin/.claude-plugin/plugin.json

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

plugin/hooks/hooks.json

@@ -19,12 +19,17 @@
         "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",
+            "command": "node \"${CLAUDE_PLUGIN_ROOT}/scripts/smart-install.js\"",
             "timeout": 300
           },
           {
             "type": "command",
-            "command": "bun \"${CLAUDE_PLUGIN_ROOT}/scripts/worker-service.cjs\" hook claude-code user-message",
+            "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 context",
             "timeout": 60
           }
         ]
@@ -35,7 +40,12 @@
         "hooks": [
           {
             "type": "command",
-            "command": "bun \"${CLAUDE_PLUGIN_ROOT}/scripts/worker-service.cjs\" hook claude-code session-init",
+            "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",
             "timeout": 60
           }
         ]
@@ -47,8 +57,13 @@
         "hooks": [
           {
             "type": "command",
-            "command": "bun \"${CLAUDE_PLUGIN_ROOT}/scripts/worker-service.cjs\" hook claude-code observation",
-            "timeout": 30
+            "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",
+            "timeout": 120
           }
         ]
       }
@@ -58,8 +73,18 @@
         "hooks": [
           {
             "type": "command",
-            "command": "bun \"${CLAUDE_PLUGIN_ROOT}/scripts/worker-service.cjs\" hook claude-code summarize",
+            "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",
             "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",
+            "timeout": 30
           }
         ]
       }

plugin/modes/code--ur.json

@@ -0,0 +1,25 @@
+{
+  "name": "Code Development (Urdu)",
+  "prompts": {
+    "footer": "IMPORTANT! DO NOT do any work right now other than generating this OBSERVATIONS from tool use messages - and remember that you are a memory agent designed to summarize a DIFFERENT claude code session, not this one.\n\nNever reference yourself or your own actions. Do not output anything other than the observation content formatted in the XML structure above. All other output is ignored by the system, and the system has been designed to be smart about token usage. Please spend your tokens wisely on useful observations.\n\nRemember that we record these observations as a way of helping us stay on track with our progress, and to help us keep important decisions and changes at the forefront of our minds! :) Thank you so much for your help!\n\nLANGUAGE REQUIREMENTS: Please write the observation data in اردو",
+
+    "xml_title_placeholder": "[**title**: بنیادی کام یا موضوع کو بیان کرنے والا مختصر عنوان]",
+    "xml_subtitle_placeholder": "[**subtitle**: ایک جملے میں وضاحت (زیادہ سے زیادہ 24 الفاظ)]",
+    "xml_fact_placeholder": "[مختصر، خود کفیل بیان]",
+    "xml_narrative_placeholder": "[**narrative**: مکمل تناسب: کیا کیا گیا، یہ کیسے کام کرتا ہے، یہ کیوں اہم ہے]",
+    "xml_concept_placeholder": "[علم-نوع-قسم]",
+    "xml_file_placeholder": "[فائل/کا/راستہ]",
+
+    "xml_summary_request_placeholder": "[مختصر عنوان جو صارف کے درخواست اور بحث/کیے گئے کام کا خلاصہ بیان کرتا ہے]",
+    "xml_summary_investigated_placeholder": "[اب تک کیا دریافت کیا گیا ہے؟ کیا جائزہ لیا گیا ہے؟]",
+    "xml_summary_learned_placeholder": "[آپ نے چیزوں کے کام کرنے کے طریقے کے بارے میں کیا سیکھا؟]",
+    "xml_summary_completed_placeholder": "[اب تک کون سا کام مکمل ہوا ہے؟ کیا بھیجا گیا یا تبدیل کیا گیا؟]",
+    "xml_summary_next_steps_placeholder": "[اس سیشن میں آپ فعال طور پر کس پر کام کر رہے ہیں یا آگے کام کرنے کا منصوبہ بنا رہے ہیں؟]",
+    "xml_summary_notes_placeholder": "[موجودہ پیشرفت پر اضافی بصیرت یا نوٹس]",
+
+    "continuation_instruction": "IMPORTANT: Continue generating observations from tool use messages using the XML structure below.\n\nLANGUAGE REQUIREMENTS: Please write the observation data in اردو",
+
+    "summary_footer": "IMPORTANT! DO NOT do any work right now other than generating this next PROGRESS SUMMARY - and remember that you are a memory agent designed to summarize a DIFFERENT claude code session, not this one.\n\nNever reference yourself or your own actions. Do not output anything other than the summary content formatted in the XML structure above. All other output is ignored by the system, and the system has been designed to be smart about token usage. Please spend your tokens wisely on useful summary content.\n\nThank you, this summary will be very useful for keeping track of our progress!\n\nLANGUAGE REQUIREMENTS: Please write ALL summary content (request, investigated, learned, completed, next_steps, notes) in اردو"
+  }
+}
+

plugin/package.json

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

plugin/scripts/bun-runner.js

@@ -0,0 +1,90 @@
+#!/usr/bin/env node
+/**
+ * Bun Runner - Finds and executes Bun even when not in PATH
+ *
+ * This script solves the fresh install problem where:
+ * 1. smart-install.js installs Bun to ~/.bun/bin/bun
+ * 2. But Bun isn't in PATH until terminal restart
+ * 3. Subsequent hooks fail because they can't find `bun`
+ *
+ * Usage: node bun-runner.js <script> [args...]
+ *
+ * Fixes #818: Worker fails to start on fresh install
+ */
+import { spawnSync, spawn } from 'child_process';
+import { existsSync } from 'fs';
+import { join } from 'path';
+import { homedir } from 'os';
+
+const IS_WINDOWS = process.platform === 'win32';
+
+/**
+ * Find Bun executable - checks PATH first, then common install locations
+ */
+function findBun() {
+  // Try PATH first
+  const pathCheck = spawnSync(IS_WINDOWS ? 'where' : 'which', ['bun'], {
+    encoding: 'utf-8',
+    stdio: ['pipe', 'pipe', 'pipe'],
+    shell: IS_WINDOWS
+  });
+
+  if (pathCheck.status === 0 && pathCheck.stdout.trim()) {
+    return 'bun'; // Found in PATH
+  }
+
+  // Check common installation paths (handles fresh installs before PATH reload)
+  // Windows: Bun installs to ~/.bun/bin/bun.exe (same as smart-install.js)
+  // Unix: Check default location plus common package manager paths
+  const bunPaths = IS_WINDOWS
+    ? [join(homedir(), '.bun', 'bin', 'bun.exe')]
+    : [
+        join(homedir(), '.bun', 'bin', 'bun'),
+        '/usr/local/bin/bun',
+        '/opt/homebrew/bin/bun',
+        '/home/linuxbrew/.linuxbrew/bin/bun'
+      ];
+
+  for (const bunPath of bunPaths) {
+    if (existsSync(bunPath)) {
+      return bunPath;
+    }
+  }
+
+  return null;
+}
+
+// Get args: node bun-runner.js <script> [args...]
+const args = process.argv.slice(2);
+
+if (args.length === 0) {
+  console.error('Usage: node bun-runner.js <script> [args...]');
+  process.exit(1);
+}
+
+const bunPath = findBun();
+
+if (!bunPath) {
+  console.error('Error: Bun not found. Please install Bun: https://bun.sh');
+  console.error('After installation, restart your terminal.');
+  process.exit(1);
+}
+
+// Spawn Bun with the provided script and args
+// Use spawn (not spawnSync) to properly handle stdio
+// Note: Don't use shell mode on Windows - it breaks paths with spaces in usernames
+// Use windowsHide to prevent a visible console window from spawning on Windows
+const child = spawn(bunPath, args, {
+  stdio: 'inherit',
+  windowsHide: true,
+  env: process.env
+});
+
+child.on('error', (err) => {
+  console.error(`Failed to start Bun: ${err.message}`);
+  process.exit(1);
+});
+
+child.on('close', (code) => {
+  process.exit(code || 0);
+});

plugin/scripts/smart-install.js

@@ -65,6 +65,36 @@ function getBunPath() {
   return null;
 }
 
+/**
+ * Minimum required bun version
+ * v1.1.14+ required for .changes property and multi-statement SQL support
+ */
+const MIN_BUN_VERSION = '1.1.14';
+
+/**
+ * Compare semver versions
+ */
+function compareVersions(v1, v2) {
+  const parts1 = v1.split('.').map(Number);
+  const parts2 = v2.split('.').map(Number);
+  for (let i = 0; i < 3; i++) {
+    const p1 = parts1[i] || 0;
+    const p2 = parts2[i] || 0;
+    if (p1 > p2) return 1;
+    if (p1 < p2) return -1;
+  }
+  return 0;
+}
+
+/**
+ * Check if bun version meets minimum requirements
+ */
+function isBunVersionSufficient() {
+  const version = getBunVersion();
+  if (!version) return false;
+  return compareVersions(version, MIN_BUN_VERSION) >= 0;
+}
+
 /**
  * Get Bun version if installed
  */
@@ -377,7 +407,7 @@ function installDeps() {
 
 // Main execution
 try {
-  // Step 1: Ensure Bun is installed (REQUIRED)
+  // Step 1: Ensure Bun is installed and meets minimum version (REQUIRED)
   if (!isBunInstalled()) {
     installBun();
 
@@ -389,6 +419,25 @@ try {
     }
   }
 
+  // Step 1.5: Ensure Bun version is sufficient
+  if (!isBunVersionSufficient()) {
+    const currentVersion = getBunVersion();
+    console.error(`⚠️  Bun ${currentVersion} is outdated. Minimum required: ${MIN_BUN_VERSION}`);
+    console.error('   Upgrading bun...');
+    try {
+      execSync('bun upgrade', { stdio: 'inherit', shell: IS_WINDOWS });
+      if (!isBunVersionSufficient()) {
+        console.error(`❌ Bun upgrade failed. Please manually upgrade: bun upgrade`);
+        process.exit(1);
+      }
+      console.error(`✅ Bun upgraded to ${getBunVersion()}`);
+    } catch (error) {
+      console.error(`❌ Failed to upgrade bun: ${error.message}`);
+      console.error('   Please manually upgrade: bun upgrade');
+      process.exit(1);
+    }
+  }
+
   // Step 2: Ensure uv is installed (REQUIRED for vector search)
   if (!isUvInstalled()) {
     installUv();

plugin/scripts/statusline-counts.js

@@ -0,0 +1,61 @@
+#!/usr/bin/env bun
+/**
+ * Statusline Counts — lightweight project-scoped observation counter
+ *
+ * Returns JSON with observation and prompt counts for the given project,
+ * suitable for integration into Claude Code's statusLineCommand.
+ *
+ * Usage:
+ *   bun statusline-counts.js <cwd>
+ *   bun statusline-counts.js /home/user/my-project
+ *
+ * Output (JSON, stdout):
+ *   {"observations": 42, "prompts": 15, "project": "my-project"}
+ *
+ * The project name is derived from basename(cwd). Observations are counted
+ * with a WHERE project = ? filter so only the current project's data is
+ * returned — preventing inflated counts from cross-project observations.
+ *
+ * Performance: ~10ms typical (direct SQLite read, no HTTP, no worker dependency)
+ */
+import { Database } from "bun:sqlite";
+import { existsSync, readFileSync } from "fs";
+import { homedir } from "os";
+import { join, basename } from "path";
+
+const cwd = process.argv[2] || process.env.CLAUDE_CWD || process.cwd();
+const project = basename(cwd);
+
+try {
+  // Resolve data directory: env var → settings.json → default
+  let dataDir = process.env.CLAUDE_MEM_DATA_DIR || join(homedir(), ".claude-mem");
+  if (!process.env.CLAUDE_MEM_DATA_DIR) {
+    const settingsPath = join(dataDir, "settings.json");
+    if (existsSync(settingsPath)) {
+      try {
+        const settings = JSON.parse(readFileSync(settingsPath, "utf-8"));
+        if (settings.CLAUDE_MEM_DATA_DIR) dataDir = settings.CLAUDE_MEM_DATA_DIR;
+      } catch { /* use default */ }
+    }
+  }
+
+  const dbPath = join(dataDir, "claude-mem.db");
+  if (!existsSync(dbPath)) {
+    console.log(JSON.stringify({ observations: 0, prompts: 0, project }));
+    process.exit(0);
+  }
+
+  const db = new Database(dbPath, { readonly: true });
+
+  const obs = db.query("SELECT COUNT(*) as c FROM observations WHERE project = ?").get(project);
+  // user_prompts links to projects through sdk_sessions.content_session_id
+  const prompts = db.query(
+    `SELECT COUNT(*) as c FROM user_prompts up
+     JOIN sdk_sessions s ON s.content_session_id = up.content_session_id
+     WHERE s.project = ?`
+  ).get(project);
+  console.log(JSON.stringify({ observations: obs.c, prompts: prompts.c, project }));
+  db.close();
+} catch (e) {
+  console.log(JSON.stringify({ observations: 0, prompts: 0, project, error: e.message }));
+}

plugin/skills/mem-search/SKILL.md

@@ -0,0 +1,141 @@
+---
+name: mem-search
+description: Search claude-mem's persistent cross-session memory database. Use when user asks "did we already solve this?", "how did we do X last time?", or needs work from previous sessions.
+---
+
+# Memory Search
+
+Search past work across all sessions. Simple workflow: search -> filter -> fetch.
+
+## When to Use
+
+Use when users ask about PREVIOUS sessions (not current conversation):
+
+- "Did we already fix this?"
+- "How did we solve X last time?"
+- "What happened last week?"
+
+## 3-Layer Workflow (ALWAYS Follow)
+
+**NEVER fetch full details without filtering first. 10x token savings.**
+
+### Step 1: Search - Get Index with IDs
+
+Use the `search` MCP tool:
+
+```
+search(query="authentication", limit=20, project="my-project")
+```
+
+**Returns:** Table with IDs, timestamps, types, titles (~50-100 tokens/result)
+
+```
+| ID | Time | T | Title | Read |
+|----|------|---|-------|------|
+| #11131 | 3:48 PM | 🟣 | Added JWT authentication | ~75 |
+| #10942 | 2:15 PM | 🔴 | Fixed auth token expiration | ~50 |
+```
+
+**Parameters:**
+
+- `query` (string) - Search term
+- `limit` (number) - Max results, default 20, max 100
+- `project` (string) - Project name filter
+- `type` (string, optional) - "observations", "sessions", or "prompts"
+- `obs_type` (string, optional) - Comma-separated: bugfix, feature, decision, discovery, change
+- `dateStart` (string, optional) - YYYY-MM-DD or epoch ms
+- `dateEnd` (string, optional) - YYYY-MM-DD or epoch ms
+- `offset` (number, optional) - Skip N results
+- `orderBy` (string, optional) - "date_desc" (default), "date_asc", "relevance"
+
+### Step 2: Timeline - Get Context Around Interesting Results
+
+Use the `timeline` MCP tool:
+
+```
+timeline(anchor=11131, depth_before=3, depth_after=3, project="my-project")
+```
+
+Or find anchor automatically from query:
+
+```
+timeline(query="authentication", depth_before=3, depth_after=3, project="my-project")
+```
+
+**Returns:** `depth_before + 1 + depth_after` items in chronological order with observations, sessions, and prompts interleaved around the anchor.
+
+**Parameters:**
+
+- `anchor` (number, optional) - Observation ID to center around
+- `query` (string, optional) - Find anchor automatically if anchor not provided
+- `depth_before` (number, optional) - Items before anchor, default 5, max 20
+- `depth_after` (number, optional) - Items after anchor, default 5, max 20
+- `project` (string) - Project name filter
+
+### Step 3: Fetch - Get Full Details ONLY for Filtered IDs
+
+Review titles from Step 1 and context from Step 2. Pick relevant IDs. Discard the rest.
+
+Use the `get_observations` MCP tool:
+
+```
+get_observations(ids=[11131, 10942])
+```
+
+**ALWAYS use `get_observations` for 2+ observations - single request vs N requests.**
+
+**Parameters:**
+
+- `ids` (array of numbers, required) - Observation IDs to fetch
+- `orderBy` (string, optional) - "date_desc" (default), "date_asc"
+- `limit` (number, optional) - Max observations to return
+- `project` (string, optional) - Project name filter
+
+**Returns:** Complete observation objects with title, subtitle, narrative, facts, concepts, files (~500-1000 tokens each)
+
+## Saving Memories
+
+Use the `save_memory` MCP tool to store manual observations:
+
+```
+save_memory(text="Important discovery about the auth system", title="Auth Architecture", project="my-project")
+```
+
+**Parameters:**
+
+- `text` (string, required) - Content to remember
+- `title` (string, optional) - Short title, auto-generated if omitted
+- `project` (string, optional) - Project name, defaults to "claude-mem"
+
+## Examples
+
+**Find recent bug fixes:**
+
+```
+search(query="bug", type="observations", obs_type="bugfix", limit=20, project="my-project")
+```
+
+**Find what happened last week:**
+
+```
+search(type="observations", dateStart="2025-11-11", limit=20, project="my-project")
+```
+
+**Understand context around a discovery:**
+
+```
+timeline(anchor=11131, depth_before=5, depth_after=5, project="my-project")
+```
+
+**Batch fetch details:**
+
+```
+get_observations(ids=[11131, 10942, 10855], orderBy="date_desc")
+```
+
+## Why This Workflow?
+
+- **Search index:** ~50-100 tokens per result
+- **Full observation:** ~500-1000 tokens each
+- **Batch fetch:** 1 HTTP request vs N individual requests
+- **10x token savings** by filtering before fetching

ragtime/CLAUDE.md

@@ -0,0 +1,22 @@
+<claude-mem-context>
+# Recent Activity
+
+### Dec 19, 2025
+
+| ID | Time | T | Title | Read |
+|----|------|---|-------|------|
+| #30153 | 8:24 PM | 🔵 | Context Builder Creates Formatted Email Investigation Context | ~384 |
+| #30152 | " | 🔵 | Ragtime Current Implementation: Manual Context Injection Via buildContextForEmail | ~357 |
+
+### Dec 20, 2025
+
+| ID | Time | T | Title | Read |
+|----|------|---|-------|------|
+| #30437 | 4:23 PM | 🔵 | Ragtime processes emails through Claude Agent SDK with claude-mem plugin | ~397 |
+| #30436 | 4:22 PM | 🔵 | Ragtime displays worker URL on localhost:37777 | ~219 |
+| #30340 | 3:42 PM | 🔄 | Relocated simple ragtime.ts to ragtime folder | ~219 |
+| #30339 | 3:41 PM | ✅ | Deleted overengineered ragtime.ts script | ~201 |
+| #30336 | 3:40 PM | 🔵 | Ragtime Email Corpus Processor Architecture | ~495 |
+| #30335 | " | 🔵 | Ragtime Uses Separate Noncommercial License | ~259 |
+| #30252 | 3:17 PM | 🟣 | Multi-Format Email Corpus Loader | ~436 |
+</claude-mem-context>

ragtime/README.md

@@ -1,19 +1,66 @@
 # Ragtime
 
-> **Status**: Not yet implemented
+Email Investigation Batch Processor using Claude-mem's email-investigation mode.
 
-Ragtime is a planned feature for claude-mem that will enable advanced timeline analysis and automated workflow orchestration.
+## Overview
 
-## Why It's Not Ready Yet
+Ragtime processes email corpus files through Claude, using the email-investigation mode for entity/relationship/timeline extraction. Each file gets a NEW session - context is managed by Claude-mem's context injection hook, not by conversation continuation.
 
-Ragtime requires a fully functional **modes system** to work properly. The modes system (implemented in PR #412) provides:
+## Features
 
-- Mode inheritance and configuration loading
-- Type-safe observation metadata
-- Dynamic prompt injection based on workflow context
-- Language-specific behavior
+- **Email-investigation mode** - Specialized observation types for entities, relationships, timeline events, anomalies
+- **Self-iterating loop** - Each file processed in a new session
+- **Transcript cleanup** - Automatic cleanup prevents buildup of old transcripts
+- **Configurable** - All paths and settings via environment variables
 
-Now that the modes system is complete, Ragtime can be fully scripted out in a future release.
+## Usage
+
+```bash
+# Basic usage (expects corpus in datasets/epstein-mode/)
+bun ragtime/ragtime.ts
+
+# With custom corpus path
+RAGTIME_CORPUS_PATH=/path/to/emails bun ragtime/ragtime.ts
+
+# Limit files for testing
+RAGTIME_FILE_LIMIT=5 bun ragtime/ragtime.ts
+```
+
+## Configuration
+
+| Environment Variable | Default | Description |
+|---------------------|---------|-------------|
+| `RAGTIME_CORPUS_PATH` | `./datasets/epstein-mode` | Path to folder containing .md email files |
+| `RAGTIME_PLUGIN_PATH` | `./plugin` | Path to claude-mem plugin |
+| `CLAUDE_MEM_WORKER_PORT` | `37777` | Worker service port |
+| `RAGTIME_TRANSCRIPT_MAX_AGE` | `24` | Max age of transcripts to keep (hours) |
+| `RAGTIME_PROJECT_NAME` | `ragtime-investigation` | Project name for grouping |
+| `RAGTIME_FILE_LIMIT` | `0` | Limit files to process (0 = all) |
+| `RAGTIME_SESSION_DELAY` | `2000` | Delay between sessions (ms) |
+
+## Corpus Format
+
+The corpus directory should contain markdown files with email content. Files are processed in numeric order based on the first number in the filename:
+
+```
+datasets/epstein-mode/
+  0001.md
+  0002.md
+  0003.md
+  ...
+```
+
+Each markdown file should contain a single email or document to analyze.
+
+## How It Works
+
+1. **Startup**: Sets `CLAUDE_MEM_MODE=email-investigation` and cleans up old transcripts
+2. **Processing**: For each file:
+   - Starts a NEW Claude session (no continuation)
+   - Claude reads the file and analyzes entities, relationships, timeline events
+   - Claude-mem's context injection hook provides relevant past observations
+   - Worker processes and stores new observations
+3. **Cleanup**: Periodic and final transcript cleanup prevents buildup
 
 ## License
 
@@ -23,9 +70,9 @@ See [LICENSE](./LICENSE) for full terms.
 
 ### What this means:
 
-- ✅ You can use ragtime for noncommercial purposes
-- ✅ You can modify and distribute it
-- ❌ You cannot use it for commercial purposes without permission
+- You can use ragtime for noncommercial purposes
+- You can modify and distribute it
+- You cannot use it for commercial purposes without permission
 
 ### Why a different license?
 

ragtime/ragtime.ts

@@ -1,93 +1,288 @@
+#!/usr/bin/env bun
+/**
+ * RAGTIME - Email Investigation Batch Processor
+ *
+ * Processes email corpus files through Claude using email-investigation mode.
+ * Each file gets a NEW session - context is managed by Claude-mem's context
+ * injection hook, not by conversation continuation.
+ *
+ * Features:
+ * - Email-investigation mode for entity/relationship/timeline extraction
+ * - Self-iterating loop (each file = new session)
+ * - Transcript cleanup to prevent buildup
+ * - Configurable paths via environment or defaults
+ */
+
 import { query } from "@anthropic-ai/claude-agent-sdk";
 import * as fs from "fs";
 import * as path from "path";
+import { homedir } from "os";
 
-const pathToFolder = "/Users/alexnewman/Scripts/claude-mem/datasets/epstein-mode/";
-const pathToPlugin = "/Users/alexnewman/Scripts/claude-mem/plugin/";
-const WORKER_PORT = 37777;
+// Configuration - can be overridden via environment variables
+const CONFIG = {
+  // Path to corpus folder containing .md files
+  corpusPath: process.env.RAGTIME_CORPUS_PATH ||
+    path.join(process.cwd(), "datasets", "epstein-mode"),
 
-// Or read from a directory
-const filesToProcess = fs
-  .readdirSync(pathToFolder)
-  .filter((f) => f.endsWith(".md"))
-  .sort((a, b) => {
-    // Extract numeric part from filename (e.g., "0001.md" -> 1)
-    const numA = parseInt(a.match(/\d+/)?.[0] || "0", 10);
-    const numB = parseInt(b.match(/\d+/)?.[0] || "0", 10);
-    return numA - numB;
-  })
-  .map((f) => path.join(pathToFolder, f));
+  // Path to claude-mem plugin
+  pluginPath: process.env.RAGTIME_PLUGIN_PATH ||
+    path.join(process.cwd(), "plugin"),
+
+  // Worker port
+  workerPort: parseInt(process.env.CLAUDE_MEM_WORKER_PORT || "37777", 10),
+
+  // Max age of transcripts to keep (in hours)
+  transcriptMaxAgeHours: parseInt(process.env.RAGTIME_TRANSCRIPT_MAX_AGE || "24", 10),
+
+  // Project name for grouping transcripts
+  projectName: process.env.RAGTIME_PROJECT_NAME || "ragtime-investigation",
+
+  // Limit files to process (0 = all)
+  fileLimit: parseInt(process.env.RAGTIME_FILE_LIMIT || "0", 10),
+
+  // Delay between sessions (ms) - gives worker time to process
+  sessionDelayMs: parseInt(process.env.RAGTIME_SESSION_DELAY || "2000", 10),
+};
+
+// Set email-investigation mode for Claude-mem
+process.env.CLAUDE_MEM_MODE = "email-investigation";
+
+/**
+ * Get list of markdown files to process, sorted numerically
+ */
+function getFilesToProcess(): string[] {
+  if (!fs.existsSync(CONFIG.corpusPath)) {
+    console.error(`Corpus path does not exist: ${CONFIG.corpusPath}`);
+    console.error("Set RAGTIME_CORPUS_PATH environment variable or create the directory");
+    process.exit(1);
+  }
+
+  const files = fs
+    .readdirSync(CONFIG.corpusPath)
+    .filter((f) => f.endsWith(".md"))
+    .sort((a, b) => {
+      // Extract numeric part from filename (e.g., "0001.md" -> 1)
+      const numA = parseInt(a.match(/\d+/)?.[0] || "0", 10);
+      const numB = parseInt(b.match(/\d+/)?.[0] || "0", 10);
+      return numA - numB;
+    })
+    .map((f) => path.join(CONFIG.corpusPath, f));
+
+  if (files.length === 0) {
+    console.error(`No .md files found in: ${CONFIG.corpusPath}`);
+    process.exit(1);
+  }
+
+  // Apply limit if set
+  if (CONFIG.fileLimit > 0) {
+    return files.slice(0, CONFIG.fileLimit);
+  }
+
+  return files;
+}
+
+/**
+ * Clean up old transcripts to prevent buildup
+ * Removes transcripts older than configured max age
+ */
+async function cleanupOldTranscripts(): Promise<void> {
+  const transcriptsBase = path.join(homedir(), ".claude", "projects");
+
+  if (!fs.existsSync(transcriptsBase)) {
+    console.log("No transcripts directory found, skipping cleanup");
+    return;
+  }
+
+  const maxAgeMs = CONFIG.transcriptMaxAgeHours * 60 * 60 * 1000;
+  const now = Date.now();
+  let cleaned = 0;
+
+  try {
+    // Walk through project directories
+    const projectDirs = fs.readdirSync(transcriptsBase);
+
+    for (const projectDir of projectDirs) {
+      const projectPath = path.join(transcriptsBase, projectDir);
+      const stat = fs.statSync(projectPath);
+
+      if (!stat.isDirectory()) continue;
+
+      // Check for .jsonl transcript files
+      const files = fs.readdirSync(projectPath);
+
+      for (const file of files) {
+        if (!file.endsWith(".jsonl")) continue;
+
+        const filePath = path.join(projectPath, file);
+        const fileStat = fs.statSync(filePath);
+        const fileAge = now - fileStat.mtimeMs;
+
+        if (fileAge > maxAgeMs) {
+          try {
+            fs.unlinkSync(filePath);
+            cleaned++;
+          } catch (err) {
+            console.warn(`Failed to delete old transcript: ${filePath}`);
+          }
+        }
+      }
+
+      // Remove empty project directories
+      const remaining = fs.readdirSync(projectPath);
+      if (remaining.length === 0) {
+        try {
+          fs.rmdirSync(projectPath);
+        } catch {
+          // Ignore - may have race condition
+        }
+      }
+    }
+
+    if (cleaned > 0) {
+      console.log(`Cleaned up ${cleaned} old transcript(s)`);
+    }
+  } catch (err) {
+    console.warn("Transcript cleanup error:", err);
+  }
+}
 
 /**
  * Poll the worker's processing status endpoint until the queue is empty
  */
 async function waitForQueueToEmpty(): Promise<void> {
   const maxWaitTimeMs = 5 * 60 * 1000; // 5 minutes maximum
-  const pollIntervalMs = 500; // Poll every 500ms
+  const pollIntervalMs = 500;
   const startTime = Date.now();
 
   while (true) {
     try {
-      const response = await fetch(`http://localhost:${WORKER_PORT}/api/processing-status`);
+      const response = await fetch(
+        `http://localhost:${CONFIG.workerPort}/api/processing-status`
+      );
+
       if (!response.ok) {
         console.error(`Failed to get processing status: ${response.status}`);
         break;
       }
 
       const status = await response.json();
-      console.log(`Queue status - Processing: ${status.isProcessing}, Queue depth: ${status.queueDepth}`);
 
       // Exit when queue is empty
       if (status.queueDepth === 0 && !status.isProcessing) {
-        console.log("Queue is empty, continuing to next prompt");
         break;
       }
 
       // Check timeout
       if (Date.now() - startTime > maxWaitTimeMs) {
-        console.warn("Warning: Queue did not empty within timeout, continuing anyway");
+        console.warn("Queue did not empty within timeout, continuing anyway");
         break;
       }
 
-      // Wait before polling again
-      await new Promise(resolve => setTimeout(resolve, pollIntervalMs));
+      await new Promise((resolve) => setTimeout(resolve, pollIntervalMs));
     } catch (error) {
       console.error("Error polling worker status:", error);
-      // On error, wait a bit and continue to avoid infinite loop
-      await new Promise(resolve => setTimeout(resolve, 1000));
+      await new Promise((resolve) => setTimeout(resolve, 1000));
       break;
     }
   }
 }
 
-// var i = 0;
+/**
+ * Process a single file in a NEW session
+ * Context is injected by Claude-mem hooks, not conversation continuation
+ */
+async function processFile(file: string, index: number, total: number): Promise<void> {
+  const filename = path.basename(file);
+  console.log(`\n[${ index + 1}/${total}] Processing: ${filename}`);
 
-for (const file of filesToProcess) {
-  // i++;
-  // Limit for testing
-  // if (i > 3) break;
+  try {
+    for await (const message of query({
+      prompt: `Read ${file} and analyze it in the context of the investigation. Look for entities, relationships, timeline events, and any anomalies. Cross-reference with what you know from the injected context above.`,
+      options: {
+        cwd: CONFIG.corpusPath,
+        plugins: [{ type: "local", path: CONFIG.pluginPath }],
+      },
+    })) {
+      // Log assistant responses
+      if (message.type === "assistant") {
+        const content = message.message.content;
+        if (Array.isArray(content)) {
+          for (const block of content) {
+            if (block.type === "text" && block.text) {
+              // Truncate long responses for console
+              const text = block.text.length > 500
+                ? block.text.substring(0, 500) + "..."
+                : block.text;
+              console.log("Assistant:", text);
+            }
+          }
+        } else if (typeof content === "string") {
+          console.log("Assistant:", content);
+        }
+      }
 
-  console.log(`\n=== Processing ${file} ===\n`);
+      // Log completion
+      if (message.type === "result" && message.subtype === "success") {
+        console.log(`Completed: ${filename}`);
+      }
+    }
+  } catch (err) {
+    console.error(`Error processing ${filename}:`, err);
+  }
+}
 
-  for await (const message of query({
-    prompt: `Read ${file} and think about how it relates to the injected context above (if any).`,
-    options: {
-      cwd: pathToFolder,
-      plugins: [{ type: "local", path: pathToPlugin }],
-    },
-  })) {
-    if (message.type === "system" && message.subtype === "init") {
-      console.log("Plugins:", message.plugins);
-      console.log("Commands:", message.slash_commands);
+/**
+ * Main execution loop
+ */
+async function main(): Promise<void> {
+  console.log("=".repeat(60));
+  console.log("RAGTIME Email Investigation Processor");
+  console.log("=".repeat(60));
+  console.log(`Mode: email-investigation`);
+  console.log(`Corpus: ${CONFIG.corpusPath}`);
+  console.log(`Plugin: ${CONFIG.pluginPath}`);
+  console.log(`Worker: http://localhost:${CONFIG.workerPort}`);
+  console.log(`Transcript cleanup: ${CONFIG.transcriptMaxAgeHours}h`);
+  console.log("=".repeat(60));
+
+  // Initial cleanup
+  await cleanupOldTranscripts();
+
+  // Get files to process
+  const files = getFilesToProcess();
+  console.log(`\nFound ${files.length} file(s) to process\n`);
+
+  // Process each file in a NEW session
+  for (let i = 0; i < files.length; i++) {
+    const file = files[i];
+
+    await processFile(file, i, files.length);
+
+    // Wait for worker to finish processing observations
+    console.log("Waiting for worker queue...");
+    await waitForQueueToEmpty();
+
+    // Delay before next session
+    if (i < files.length - 1 && CONFIG.sessionDelayMs > 0) {
+      await new Promise((resolve) => setTimeout(resolve, CONFIG.sessionDelayMs));
     }
 
-    if (message.type === "assistant") {
-      console.log("Assistant:", message.message.content);
+    // Periodic transcript cleanup (every 10 files)
+    if ((i + 1) % 10 === 0) {
+      await cleanupOldTranscripts();
     }
-    console.log("Raw:",  JSON.stringify(message, null, 2));
   }
 
-  // Wait for the worker queue to be empty before continuing to the next file
-  console.log("\n=== Waiting for worker queue to empty ===\n");
-  await waitForQueueToEmpty();
+  // Final cleanup
+  await cleanupOldTranscripts();
+
+  console.log("\n" + "=".repeat(60));
+  console.log("Investigation complete");
+  console.log("=".repeat(60));
 }
+
+// Run
+main().catch((err) => {
+  console.error("Fatal error:", err);
+  process.exit(1);
+});

scripts/translate-readme/cli.ts

@@ -88,6 +88,7 @@ function printLanguages(): void {
     th: "Thai",
     hi: "Hindi",
     bn: "Bengali",
+    ur: "Urdu",
     ro: "Romanian",
     sv: "Swedish",
     // Tier 4 - Why not

scripts/translate-readme/index.ts

@@ -92,6 +92,7 @@ const LANGUAGE_NAMES: Record<string, string> = {
   th: "Thai",
   hi: "Hindi",
   bn: "Bengali",
+  ur: "Urdu",
   ro: "Romanian",
   sv: "Swedish",
   // Tier 4 - Why not

src/cli/adapters/CLAUDE.md

@@ -0,0 +1,3 @@
+<claude-mem-context>
+
+</claude-mem-context>

src/cli/claude-md-commands.ts

@@ -0,0 +1,540 @@
+/**
+ * CLAUDE.md Generation and Cleanup Commands
+ *
+ * Shared module for CLAUDE.md file management that can be invoked from:
+ * - CLI: `claude-mem generate` / `claude-mem clean`
+ * - Worker service API endpoints
+ *
+ * Provides two main operations:
+ * - generateClaudeMd: Regenerate CLAUDE.md files for folders with observations
+ * - cleanClaudeMd: Remove auto-generated content from CLAUDE.md files
+ */
+
+import { Database } from 'bun:sqlite';
+import path from 'path';
+import os from 'os';
+import {
+  existsSync,
+  writeFileSync,
+  readFileSync,
+  renameSync,
+  unlinkSync,
+  readdirSync
+} from 'fs';
+import { execSync } from 'child_process';
+import { SettingsDefaultsManager } from '../shared/SettingsDefaultsManager.js';
+import { formatTime, groupByDate } from '../shared/timeline-formatting.js';
+import { isDirectChild } from '../shared/path-utils.js';
+import { logger } from '../utils/logger.js';
+
+const DB_PATH = path.join(os.homedir(), '.claude-mem', 'claude-mem.db');
+const SETTINGS_PATH = path.join(os.homedir(), '.claude-mem', 'settings.json');
+
+interface ObservationRow {
+  id: number;
+  title: string | null;
+  subtitle: string | null;
+  narrative: string | null;
+  facts: string | null;
+  type: string;
+  created_at: string;
+  created_at_epoch: number;
+  files_modified: string | null;
+  files_read: string | null;
+  project: string;
+  discovery_tokens: number | null;
+}
+
+// Type icon map (matches ModeManager)
+const TYPE_ICONS: Record<string, string> = {
+  'bugfix': '🔴',
+  'feature': '🟣',
+  'refactor': '🔄',
+  'change': '✅',
+  'discovery': '🔵',
+  'decision': '⚖️',
+  'session': '🎯',
+  'prompt': '💬'
+};
+
+function getTypeIcon(type: string): string {
+  return TYPE_ICONS[type] || '📝';
+}
+
+function estimateTokens(obs: ObservationRow): number {
+  const size = (obs.title?.length || 0) +
+    (obs.subtitle?.length || 0) +
+    (obs.narrative?.length || 0) +
+    (obs.facts?.length || 0);
+  return Math.ceil(size / 4);
+}
+
+/**
+ * Get tracked folders using git ls-files.
+ * Respects .gitignore and only returns folders within the project.
+ */
+function getTrackedFolders(workingDir: string): Set<string> {
+  const folders = new Set<string>();
+
+  try {
+    const output = execSync('git ls-files', {
+      cwd: workingDir,
+      encoding: 'utf-8',
+      maxBuffer: 50 * 1024 * 1024
+    });
+
+    const files = output.trim().split('\n').filter(f => f);
+
+    for (const file of files) {
+      const absPath = path.join(workingDir, file);
+      let dir = path.dirname(absPath);
+
+      while (dir.length > workingDir.length && dir.startsWith(workingDir)) {
+        folders.add(dir);
+        dir = path.dirname(dir);
+      }
+    }
+  } catch (error) {
+    logger.warn('CLAUDE_MD', 'git ls-files failed, falling back to directory walk', { error: String(error) });
+    walkDirectoriesWithIgnore(workingDir, folders);
+  }
+
+  return folders;
+}
+
+/**
+ * Fallback directory walker that skips common ignored patterns.
+ */
+function walkDirectoriesWithIgnore(dir: string, folders: Set<string>, depth: number = 0): void {
+  if (depth > 10) return;
+
+  const ignorePatterns = [
+    'node_modules', '.git', '.next', 'dist', 'build', '.cache',
+    '__pycache__', '.venv', 'venv', '.idea', '.vscode', 'coverage',
+    '.claude-mem', '.open-next', '.turbo'
+  ];
+
+  try {
+    const entries = readdirSync(dir, { withFileTypes: true });
+    for (const entry of entries) {
+      if (!entry.isDirectory()) continue;
+      if (ignorePatterns.includes(entry.name)) continue;
+      if (entry.name.startsWith('.') && entry.name !== '.claude') continue;
+
+      const fullPath = path.join(dir, entry.name);
+      folders.add(fullPath);
+      walkDirectoriesWithIgnore(fullPath, folders, depth + 1);
+    }
+  } catch {
+    // Ignore permission errors
+  }
+}
+
+/**
+ * Check if an observation has any files that are direct children of the folder.
+ */
+function hasDirectChildFile(obs: ObservationRow, folderPath: string): boolean {
+  const checkFiles = (filesJson: string | null): boolean => {
+    if (!filesJson) return false;
+    try {
+      const files = JSON.parse(filesJson);
+      if (Array.isArray(files)) {
+        return files.some(f => isDirectChild(f, folderPath));
+      }
+    } catch {}
+    return false;
+  };
+
+  return checkFiles(obs.files_modified) || checkFiles(obs.files_read);
+}
+
+/**
+ * Query observations for a specific folder.
+ * Only returns observations with files directly in the folder (not in subfolders).
+ */
+function findObservationsByFolder(db: Database, relativeFolderPath: string, project: string, limit: number): ObservationRow[] {
+  const queryLimit = limit * 3;
+
+  const sql = `
+    SELECT o.*, o.discovery_tokens
+    FROM observations o
+    WHERE o.project = ?
+      AND (o.files_modified LIKE ? OR o.files_read LIKE ?)
+    ORDER BY o.created_at_epoch DESC
+    LIMIT ?
+  `;
+
+  // Database stores paths with forward slashes (git-normalized)
+  const normalizedFolderPath = relativeFolderPath.split(path.sep).join('/');
+  const likePattern = `%"${normalizedFolderPath}/%`;
+  const allMatches = db.prepare(sql).all(project, likePattern, likePattern, queryLimit) as ObservationRow[];
+
+  return allMatches.filter(obs => hasDirectChildFile(obs, relativeFolderPath)).slice(0, limit);
+}
+
+/**
+ * Extract relevant file from an observation for display.
+ * Only returns files that are direct children of the folder.
+ */
+function extractRelevantFile(obs: ObservationRow, relativeFolder: string): string {
+  if (obs.files_modified) {
+    try {
+      const modified = JSON.parse(obs.files_modified);
+      if (Array.isArray(modified)) {
+        for (const file of modified) {
+          if (isDirectChild(file, relativeFolder)) {
+            return path.basename(file);
+          }
+        }
+      }
+    } catch {}
+  }
+
+  if (obs.files_read) {
+    try {
+      const read = JSON.parse(obs.files_read);
+      if (Array.isArray(read)) {
+        for (const file of read) {
+          if (isDirectChild(file, relativeFolder)) {
+            return path.basename(file);
+          }
+        }
+      }
+    } catch {}
+  }
+
+  return 'General';
+}
+
+/**
+ * Format observations for CLAUDE.md content.
+ */
+function formatObservationsForClaudeMd(observations: ObservationRow[], folderPath: string): string {
+  const lines: string[] = [];
+  lines.push('# Recent Activity');
+  lines.push('');
+  lines.push('<!-- This section is auto-generated by claude-mem. Edit content outside the tags. -->');
+  lines.push('');
+
+  if (observations.length === 0) {
+    lines.push('*No recent activity*');
+    return lines.join('\n');
+  }
+
+  const byDate = groupByDate(observations, obs => obs.created_at);
+
+  for (const [day, dayObs] of byDate) {
+    lines.push(`### ${day}`);
+    lines.push('');
+
+    const byFile = new Map<string, ObservationRow[]>();
+    for (const obs of dayObs) {
+      const file = extractRelevantFile(obs, folderPath);
+      if (!byFile.has(file)) byFile.set(file, []);
+      byFile.get(file)!.push(obs);
+    }
+
+    for (const [file, fileObs] of byFile) {
+      lines.push(`**${file}**`);
+      lines.push('| ID | Time | T | Title | Read |');
+      lines.push('|----|------|---|-------|------|');
+
+      let lastTime = '';
+      for (const obs of fileObs) {
+        const time = formatTime(obs.created_at_epoch);
+        const timeDisplay = time === lastTime ? '"' : time;
+        lastTime = time;
+
+        const icon = getTypeIcon(obs.type);
+        const title = obs.title || 'Untitled';
+        const tokens = estimateTokens(obs);
+
+        lines.push(`| #${obs.id} | ${timeDisplay} | ${icon} | ${title} | ~${tokens} |`);
+      }
+
+      lines.push('');
+    }
+  }
+
+  return lines.join('\n').trim();
+}
+
+/**
+ * Write CLAUDE.md file with tagged content preservation.
+ * Only writes to folders that exist — never creates directories.
+ */
+function writeClaudeMdToFolder(folderPath: string, newContent: string): void {
+  const claudeMdPath = path.join(folderPath, 'CLAUDE.md');
+  const tempFile = `${claudeMdPath}.tmp`;
+
+  if (!existsSync(folderPath)) {
+    throw new Error(`Folder does not exist: ${folderPath}`);
+  }
+
+  let existingContent = '';
+  if (existsSync(claudeMdPath)) {
+    existingContent = readFileSync(claudeMdPath, 'utf-8');
+  }
+
+  const startTag = '<claude-mem-context>';
+  const endTag = '</claude-mem-context>';
+
+  let finalContent: string;
+  if (!existingContent) {
+    finalContent = `${startTag}\n${newContent}\n${endTag}`;
+  } else {
+    const startIdx = existingContent.indexOf(startTag);
+    const endIdx = existingContent.indexOf(endTag);
+
+    if (startIdx !== -1 && endIdx !== -1) {
+      finalContent = existingContent.substring(0, startIdx) +
+        `${startTag}\n${newContent}\n${endTag}` +
+        existingContent.substring(endIdx + endTag.length);
+    } else {
+      finalContent = existingContent + `\n\n${startTag}\n${newContent}\n${endTag}`;
+    }
+  }
+
+  writeFileSync(tempFile, finalContent);
+  renameSync(tempFile, claudeMdPath);
+}
+
+/**
+ * Regenerate CLAUDE.md for a single folder.
+ */
+function regenerateFolder(
+  db: Database,
+  absoluteFolder: string,
+  relativeFolder: string,
+  project: string,
+  dryRun: boolean,
+  workingDir: string,
+  observationLimit: number
+): { success: boolean; observationCount: number; error?: string } {
+  try {
+    if (!existsSync(absoluteFolder)) {
+      return { success: false, observationCount: 0, error: 'Folder no longer exists' };
+    }
+
+    // Validate folder is within project root (prevent path traversal)
+    const resolvedFolder = path.resolve(absoluteFolder);
+    const resolvedWorkingDir = path.resolve(workingDir);
+    if (!resolvedFolder.startsWith(resolvedWorkingDir + path.sep)) {
+      return { success: false, observationCount: 0, error: 'Path escapes project root' };
+    }
+
+    const observations = findObservationsByFolder(db, relativeFolder, project, observationLimit);
+
+    if (observations.length === 0) {
+      return { success: false, observationCount: 0, error: 'No observations for folder' };
+    }
+
+    if (dryRun) {
+      return { success: true, observationCount: observations.length };
+    }
+
+    const formatted = formatObservationsForClaudeMd(observations, relativeFolder);
+    writeClaudeMdToFolder(absoluteFolder, formatted);
+
+    return { success: true, observationCount: observations.length };
+  } catch (error) {
+    return { success: false, observationCount: 0, error: String(error) };
+  }
+}
+
+/**
+ * Generate CLAUDE.md files for all folders with observations.
+ *
+ * @param dryRun - If true, only report what would be done without writing files
+ * @returns Exit code (0 for success, 1 for error)
+ */
+export async function generateClaudeMd(dryRun: boolean): Promise<number> {
+  try {
+    const workingDir = process.cwd();
+    const settings = SettingsDefaultsManager.loadFromFile(SETTINGS_PATH);
+    const observationLimit = parseInt(settings.CLAUDE_MEM_CONTEXT_OBSERVATIONS, 10) || 50;
+
+    logger.info('CLAUDE_MD', 'Starting CLAUDE.md generation', {
+      workingDir,
+      dryRun,
+      observationLimit
+    });
+
+    const project = path.basename(workingDir);
+    const trackedFolders = getTrackedFolders(workingDir);
+
+    if (trackedFolders.size === 0) {
+      logger.info('CLAUDE_MD', 'No folders found in project');
+      return 0;
+    }
+
+    logger.info('CLAUDE_MD', `Found ${trackedFolders.size} folders in project`);
+
+    if (!existsSync(DB_PATH)) {
+      logger.info('CLAUDE_MD', 'Database not found, no observations to process');
+      return 0;
+    }
+
+    const db = new Database(DB_PATH, { readonly: true, create: false });
+
+    let successCount = 0;
+    let skipCount = 0;
+    let errorCount = 0;
+
+    const foldersArray = Array.from(trackedFolders).sort();
+
+    for (const absoluteFolder of foldersArray) {
+      const relativeFolder = path.relative(workingDir, absoluteFolder);
+
+      const result = regenerateFolder(
+        db,
+        absoluteFolder,
+        relativeFolder,
+        project,
+        dryRun,
+        workingDir,
+        observationLimit
+      );
+
+      if (result.success) {
+        logger.debug('CLAUDE_MD', `Processed folder: ${relativeFolder}`, {
+          observationCount: result.observationCount
+        });
+        successCount++;
+      } else if (result.error?.includes('No observations')) {
+        skipCount++;
+      } else {
+        logger.warn('CLAUDE_MD', `Error processing folder: ${relativeFolder}`, {
+          error: result.error
+        });
+        errorCount++;
+      }
+    }
+
+    db.close();
+
+    logger.info('CLAUDE_MD', 'CLAUDE.md generation complete', {
+      totalFolders: foldersArray.length,
+      withObservations: successCount,
+      noObservations: skipCount,
+      errors: errorCount,
+      dryRun
+    });
+
+    return 0;
+  } catch (error) {
+    logger.error('CLAUDE_MD', 'Fatal error during CLAUDE.md generation', {
+      error: String(error)
+    });
+    return 1;
+  }
+}
+
+/**
+ * Clean up auto-generated CLAUDE.md files.
+ *
+ * For each file with <claude-mem-context> tags:
+ * - Strip the tagged section
+ * - If empty after stripping, delete the file
+ * - If has remaining content, save the stripped version
+ *
+ * @param dryRun - If true, only report what would be done without modifying files
+ * @returns Exit code (0 for success, 1 for error)
+ */
+export async function cleanClaudeMd(dryRun: boolean): Promise<number> {
+  try {
+    const workingDir = process.cwd();
+
+    logger.info('CLAUDE_MD', 'Starting CLAUDE.md cleanup', {
+      workingDir,
+      dryRun
+    });
+
+    const filesToProcess: string[] = [];
+
+    function walkForClaudeMd(dir: string): void {
+      const ignorePatterns = [
+        'node_modules', '.git', '.next', 'dist', 'build', '.cache',
+        '__pycache__', '.venv', 'venv', '.idea', '.vscode', 'coverage',
+        '.claude-mem', '.open-next', '.turbo'
+      ];
+
+      try {
+        const entries = readdirSync(dir, { withFileTypes: true });
+        for (const entry of entries) {
+          const fullPath = path.join(dir, entry.name);
+
+          if (entry.isDirectory()) {
+            if (!ignorePatterns.includes(entry.name)) {
+              walkForClaudeMd(fullPath);
+            }
+          } else if (entry.name === 'CLAUDE.md') {
+            try {
+              const content = readFileSync(fullPath, 'utf-8');
+              if (content.includes('<claude-mem-context>')) {
+                filesToProcess.push(fullPath);
+              }
+            } catch {
+              // Skip files we can't read
+            }
+          }
+        }
+      } catch {
+        // Ignore permission errors
+      }
+    }
+
+    walkForClaudeMd(workingDir);
+
+    if (filesToProcess.length === 0) {
+      logger.info('CLAUDE_MD', 'No CLAUDE.md files with auto-generated content found');
+      return 0;
+    }
+
+    logger.info('CLAUDE_MD', `Found ${filesToProcess.length} CLAUDE.md files with auto-generated content`);
+
+    let deletedCount = 0;
+    let cleanedCount = 0;
+    let errorCount = 0;
+
+    for (const file of filesToProcess) {
+      const relativePath = path.relative(workingDir, file);
+
+      try {
+        const content = readFileSync(file, 'utf-8');
+        const stripped = content.replace(/<claude-mem-context>[\s\S]*?<\/claude-mem-context>/g, '').trim();
+
+        if (stripped === '') {
+          if (!dryRun) {
+            unlinkSync(file);
+          }
+          logger.debug('CLAUDE_MD', `${dryRun ? '[DRY-RUN] Would delete' : 'Deleted'} (empty): ${relativePath}`);
+          deletedCount++;
+        } else {
+          if (!dryRun) {
+            writeFileSync(file, stripped);
+          }
+          logger.debug('CLAUDE_MD', `${dryRun ? '[DRY-RUN] Would clean' : 'Cleaned'}: ${relativePath}`);
+          cleanedCount++;
+        }
+      } catch (error) {
+        logger.warn('CLAUDE_MD', `Error processing ${relativePath}`, { error: String(error) });
+        errorCount++;
+      }
+    }
+
+    logger.info('CLAUDE_MD', 'CLAUDE.md cleanup complete', {
+      deleted: deletedCount,
+      cleaned: cleanedCount,
+      errors: errorCount,
+      dryRun
+    });
+
+    return 0;
+  } catch (error) {
+    logger.error('CLAUDE_MD', 'Fatal error during CLAUDE.md cleanup', {
+      error: String(error)
+    });
+    return 1;
+  }
+}

src/cli/handlers/CLAUDE.md

@@ -1,7 +1,3 @@
 <claude-mem-context>
-# Recent Activity
 
-<!-- This section is auto-generated by claude-mem. Edit content outside the tags. -->
-
-*No recent activity*
 </claude-mem-context>

src/cli/handlers/context.ts

@@ -9,6 +9,7 @@ import type { EventHandler, NormalizedHookInput, HookResult } from '../types.js'
 import { ensureWorkerRunning, getWorkerPort } from '../../shared/worker-utils.js';
 import { getProjectContext } from '../../utils/project-name.js';
 import { HOOK_EXIT_CODES } from '../../shared/hook-constants.js';
+import { logger } from '../../utils/logger.js';
 
 export const contextHandler: EventHandler = {
   async execute(input: NormalizedHookInput): Promise<HookResult> {
@@ -35,20 +36,34 @@ export const contextHandler: EventHandler = {
 
     // Note: Removed AbortSignal.timeout due to Windows Bun cleanup issue (libuv assertion)
     // Worker service has its own timeouts, so client-side timeout is redundant
-    const response = await fetch(url);
+    try {
+      const response = await fetch(url);
 
-    if (!response.ok) {
-      throw new Error(`Context generation failed: ${response.status}`);
-    }
-
-    const result = await response.text();
-    const additionalContext = result.trim();
-
-    return {
-      hookSpecificOutput: {
-        hookEventName: 'SessionStart',
-        additionalContext
+      if (!response.ok) {
+        // Log but don't throw — context fetch failure should not block session start
+        logger.warn('HOOK', 'Context generation failed, returning empty', { status: response.status });
+        return {
+          hookSpecificOutput: { hookEventName: 'SessionStart', additionalContext: '' },
+          exitCode: HOOK_EXIT_CODES.SUCCESS
+        };
       }
-    };
+
+      const result = await response.text();
+      const additionalContext = result.trim();
+
+      return {
+        hookSpecificOutput: {
+          hookEventName: 'SessionStart',
+          additionalContext
+        }
+      };
+    } catch (error) {
+      // Worker unreachable — return empty context gracefully
+      logger.warn('HOOK', 'Context fetch error, returning empty', { error: error instanceof Error ? error.message : String(error) });
+      return {
+        hookSpecificOutput: { hookEventName: 'SessionStart', additionalContext: '' },
+        exitCode: HOOK_EXIT_CODES.SUCCESS
+      };
+    }
   }
 };

src/cli/handlers/file-edit.ts

@@ -39,25 +39,33 @@ export const fileEditHandler: EventHandler = {
 
     // Send to worker as an observation with file edit metadata
     // The observation handler on the worker will process this appropriately
-    const response = await fetch(`http://127.0.0.1:${port}/api/sessions/observations`, {
-      method: 'POST',
-      headers: { 'Content-Type': 'application/json' },
-      body: JSON.stringify({
-        contentSessionId: sessionId,
-        tool_name: 'write_file',
-        tool_input: { filePath, edits },
-        tool_response: { success: true },
-        cwd
-      })
-      // Note: Removed signal to avoid Windows Bun cleanup issue (libuv assertion)
-    });
+    try {
+      const response = await fetch(`http://127.0.0.1:${port}/api/sessions/observations`, {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({
+          contentSessionId: sessionId,
+          tool_name: 'write_file',
+          tool_input: { filePath, edits },
+          tool_response: { success: true },
+          cwd
+        })
+        // Note: Removed signal to avoid Windows Bun cleanup issue (libuv assertion)
+      });
 
-    if (!response.ok) {
-      throw new Error(`File edit observation storage failed: ${response.status}`);
+      if (!response.ok) {
+        // Log but don't throw — file edit observation failure should not block editing
+        logger.warn('HOOK', 'File edit observation storage failed, skipping', { status: response.status, filePath });
+        return { continue: true, suppressOutput: true, exitCode: HOOK_EXIT_CODES.SUCCESS };
+      }
+
+      logger.debug('HOOK', 'File edit observation sent successfully', { filePath });
+    } catch (error) {
+      // Worker unreachable — skip file edit observation gracefully
+      logger.warn('HOOK', 'File edit observation fetch error, skipping', { error: error instanceof Error ? error.message : String(error) });
+      return { continue: true, suppressOutput: true, exitCode: HOOK_EXIT_CODES.SUCCESS };
     }
 
-    logger.debug('HOOK', 'File edit observation sent successfully', { filePath });
-
     return { continue: true, suppressOutput: true };
   }
 };

src/cli/handlers/index.ts

@@ -5,26 +5,30 @@
  */
 
 import type { EventHandler } from '../types.js';
+import { HOOK_EXIT_CODES } from '../../shared/hook-constants.js';
 import { contextHandler } from './context.js';
 import { sessionInitHandler } from './session-init.js';
 import { observationHandler } from './observation.js';
 import { summarizeHandler } from './summarize.js';
 import { userMessageHandler } from './user-message.js';
 import { fileEditHandler } from './file-edit.js';
+import { sessionCompleteHandler } from './session-complete.js';
 
 export type EventType =
-  | 'context'        // SessionStart - inject context
-  | 'session-init'   // UserPromptSubmit - initialize session
-  | 'observation'    // PostToolUse - save observation
-  | 'summarize'      // Stop - generate summary
-  | 'user-message'   // SessionStart (parallel) - display to user
-  | 'file-edit';     // Cursor afterFileEdit
+  | 'context'           // SessionStart - inject context
+  | 'session-init'      // UserPromptSubmit - initialize session
+  | 'observation'       // PostToolUse - save observation
+  | 'summarize'         // Stop - generate summary (phase 1)
+  | 'session-complete'  // Stop - complete session (phase 2) - fixes #842
+  | 'user-message'      // SessionStart (parallel) - display to user
+  | 'file-edit';        // Cursor afterFileEdit
 
 const handlers: Record<EventType, EventHandler> = {
   'context': contextHandler,
   'session-init': sessionInitHandler,
   'observation': observationHandler,
   'summarize': summarizeHandler,
+  'session-complete': sessionCompleteHandler,
   'user-message': userMessageHandler,
   'file-edit': fileEditHandler
 };
@@ -32,14 +36,22 @@ const handlers: Record<EventType, EventHandler> = {
 /**
  * Get the event handler for a given event type.
  *
+ * Returns a no-op handler for unknown event types instead of throwing (fix #984).
+ * Claude Code may send new event types that the plugin doesn't handle yet —
+ * throwing would surface as a BLOCKING_ERROR to the user.
+ *
  * @param eventType The type of event to handle
- * @returns The appropriate EventHandler
- * @throws Error if event type is not recognized
+ * @returns The appropriate EventHandler, or a no-op handler for unknown types
  */
-export function getEventHandler(eventType: EventType): EventHandler {
-  const handler = handlers[eventType];
+export function getEventHandler(eventType: string): EventHandler {
+  const handler = handlers[eventType as EventType];
   if (!handler) {
-    throw new Error(`Unknown event type: ${eventType}`);
+    console.error(`[claude-mem] Unknown event type: ${eventType}, returning no-op`);
+    return {
+      async execute() {
+        return { continue: true, suppressOutput: true, exitCode: HOOK_EXIT_CODES.SUCCESS };
+      }
+    };
   }
   return handler;
 }
@@ -51,3 +63,4 @@ export { observationHandler } from './observation.js';
 export { summarizeHandler } from './summarize.js';
 export { userMessageHandler } from './user-message.js';
 export { fileEditHandler } from './file-edit.js';
+export { sessionCompleteHandler } from './session-complete.js';

src/cli/handlers/observation.ts

@@ -8,6 +8,9 @@ import type { EventHandler, NormalizedHookInput, HookResult } from '../types.js'
 import { ensureWorkerRunning, getWorkerPort } from '../../shared/worker-utils.js';
 import { logger } from '../../utils/logger.js';
 import { HOOK_EXIT_CODES } from '../../shared/hook-constants.js';
+import { isProjectExcluded } from '../../utils/project-filter.js';
+import { SettingsDefaultsManager } from '../../shared/SettingsDefaultsManager.js';
+import { USER_SETTINGS_PATH } from '../../shared/paths.js';
 
 export const observationHandler: EventHandler = {
   async execute(input: NormalizedHookInput): Promise<HookResult> {
@@ -37,25 +40,40 @@ export const observationHandler: EventHandler = {
       throw new Error(`Missing cwd in PostToolUse hook input for session ${sessionId}, tool ${toolName}`);
     }
 
-    // Send to worker - worker handles privacy check and database operations
-    const response = await fetch(`http://127.0.0.1:${port}/api/sessions/observations`, {
-      method: 'POST',
-      headers: { 'Content-Type': 'application/json' },
-      body: JSON.stringify({
-        contentSessionId: sessionId,
-        tool_name: toolName,
-        tool_input: toolInput,
-        tool_response: toolResponse,
-        cwd
-      })
-      // Note: Removed signal to avoid Windows Bun cleanup issue (libuv assertion)
-    });
-
-    if (!response.ok) {
-      throw new Error(`Observation storage failed: ${response.status}`);
+    // Check if project is excluded from tracking
+    const settings = SettingsDefaultsManager.loadFromFile(USER_SETTINGS_PATH);
+    if (isProjectExcluded(cwd, settings.CLAUDE_MEM_EXCLUDED_PROJECTS)) {
+      logger.debug('HOOK', 'Project excluded from tracking, skipping observation', { cwd, toolName });
+      return { continue: true, suppressOutput: true };
     }
 
-    logger.debug('HOOK', 'Observation sent successfully', { toolName });
+    // Send to worker - worker handles privacy check and database operations
+    try {
+      const response = await fetch(`http://127.0.0.1:${port}/api/sessions/observations`, {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({
+          contentSessionId: sessionId,
+          tool_name: toolName,
+          tool_input: toolInput,
+          tool_response: toolResponse,
+          cwd
+        })
+        // Note: Removed signal to avoid Windows Bun cleanup issue (libuv assertion)
+      });
+
+      if (!response.ok) {
+        // Log but don't throw — observation storage failure should not block tool use
+        logger.warn('HOOK', 'Observation storage failed, skipping', { status: response.status, toolName });
+        return { continue: true, suppressOutput: true, exitCode: HOOK_EXIT_CODES.SUCCESS };
+      }
+
+      logger.debug('HOOK', 'Observation sent successfully', { toolName });
+    } catch (error) {
+      // Worker unreachable — skip observation gracefully
+      logger.warn('HOOK', 'Observation fetch error, skipping', { error: error instanceof Error ? error.message : String(error) });
+      return { continue: true, suppressOutput: true, exitCode: HOOK_EXIT_CODES.SUCCESS };
+    }
 
     return { continue: true, suppressOutput: true };
   }

src/cli/handlers/session-complete.ts

@@ -0,0 +1,66 @@
+/**
+ * Session Complete Handler - Stop (Phase 2)
+ *
+ * Completes the session after summarize has been queued.
+ * This removes the session from the active sessions map, allowing
+ * the orphan reaper to clean up any remaining subprocess.
+ *
+ * Fixes Issue #842: Orphan reaper starts but never reaps because
+ * sessions stay in the active sessions map forever.
+ */
+
+import type { EventHandler, NormalizedHookInput, HookResult } from '../types.js';
+import { ensureWorkerRunning, getWorkerPort } from '../../shared/worker-utils.js';
+import { logger } from '../../utils/logger.js';
+
+export const sessionCompleteHandler: EventHandler = {
+  async execute(input: NormalizedHookInput): Promise<HookResult> {
+    // Ensure worker is running
+    const workerReady = await ensureWorkerRunning();
+    if (!workerReady) {
+      // Worker not available — skip session completion gracefully
+      return { continue: true, suppressOutput: true };
+    }
+
+    const { sessionId } = input;
+    const port = getWorkerPort();
+
+    if (!sessionId) {
+      logger.warn('HOOK', 'session-complete: Missing sessionId, skipping');
+      return { continue: true, suppressOutput: true };
+    }
+
+    logger.info('HOOK', '→ session-complete: Removing session from active map', {
+      workerPort: port,
+      contentSessionId: sessionId
+    });
+
+    try {
+      // Call the session complete endpoint by contentSessionId
+      const response = await fetch(`http://127.0.0.1:${port}/api/sessions/complete`, {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({
+          contentSessionId: sessionId
+        })
+      });
+
+      if (!response.ok) {
+        const text = await response.text();
+        logger.warn('HOOK', 'session-complete: Failed to complete session', {
+          status: response.status,
+          body: text
+        });
+      } else {
+        logger.info('HOOK', 'Session completed successfully', { contentSessionId: sessionId });
+      }
+    } catch (error) {
+      // Log but don't fail - session may already be gone
+      logger.warn('HOOK', 'session-complete: Error completing session', {
+        error: (error as Error).message
+      });
+    }
+
+    return { continue: true, suppressOutput: true };
+  }
+};

src/cli/handlers/session-init.ts

@@ -9,6 +9,9 @@ import { ensureWorkerRunning, getWorkerPort } from '../../shared/worker-utils.js
 import { getProjectName } from '../../utils/project-name.js';
 import { logger } from '../../utils/logger.js';
 import { HOOK_EXIT_CODES } from '../../shared/hook-constants.js';
+import { isProjectExcluded } from '../../utils/project-filter.js';
+import { SettingsDefaultsManager } from '../../shared/SettingsDefaultsManager.js';
+import { USER_SETTINGS_PATH } from '../../shared/paths.js';
 
 export const sessionInitHandler: EventHandler = {
   async execute(input: NormalizedHookInput): Promise<HookResult> {
@@ -19,12 +22,19 @@ export const sessionInitHandler: EventHandler = {
       return { continue: true, suppressOutput: true, exitCode: HOOK_EXIT_CODES.SUCCESS };
     }
 
-    const { sessionId, cwd, prompt } = input;
+    const { sessionId, cwd, prompt: rawPrompt } = input;
 
-    if (!prompt) {
-      throw new Error('sessionInitHandler requires prompt');
+    // Check if project is excluded from tracking
+    const settings = SettingsDefaultsManager.loadFromFile(USER_SETTINGS_PATH);
+    if (cwd && isProjectExcluded(cwd, settings.CLAUDE_MEM_EXCLUDED_PROJECTS)) {
+      logger.info('HOOK', 'Project excluded from tracking', { cwd });
+      return { continue: true, suppressOutput: true };
     }
 
+    // Handle image-only prompts (where text prompt is empty/undefined)
+    // Use placeholder so sessions still get created and tracked for memory
+    const prompt = (!rawPrompt || !rawPrompt.trim()) ? '[media prompt]' : rawPrompt;
+
     const project = getProjectName(cwd);
     const port = getWorkerPort();
 
@@ -43,7 +53,9 @@ export const sessionInitHandler: EventHandler = {
     });
 
     if (!initResponse.ok) {
-      throw new Error(`Session initialization failed: ${initResponse.status}`);
+      // Log but don't throw - a worker 500 should not block the user's prompt
+      logger.failure('HOOK', `Session initialization failed: ${initResponse.status}`, { contentSessionId: sessionId, project });
+      return { continue: true, suppressOutput: true, exitCode: HOOK_EXIT_CODES.SUCCESS };
     }
 
     const initResult = await initResponse.json() as {
@@ -86,7 +98,8 @@ export const sessionInitHandler: EventHandler = {
       });
 
       if (!response.ok) {
-        throw new Error(`SDK agent start failed: ${response.status}`);
+        // Log but don't throw - SDK agent failure should not block the user's prompt
+        logger.failure('HOOK', `SDK agent start failed: ${response.status}`, { sessionDbId, promptNumber });
       }
     } else if (input.platform === 'cursor') {
       logger.debug('HOOK', 'session-init: Skipping SDK agent init for Cursor platform', { sessionDbId, promptNumber });

src/cli/handlers/summarize.ts

@@ -7,10 +7,12 @@
  */
 
 import type { EventHandler, NormalizedHookInput, HookResult } from '../types.js';
-import { ensureWorkerRunning, getWorkerPort } from '../../shared/worker-utils.js';
+import { ensureWorkerRunning, getWorkerPort, fetchWithTimeout } from '../../shared/worker-utils.js';
 import { logger } from '../../utils/logger.js';
 import { extractLastMessage } from '../../shared/transcript-parser.js';
-import { HOOK_EXIT_CODES } from '../../shared/hook-constants.js';
+import { HOOK_EXIT_CODES, HOOK_TIMEOUTS, getTimeout } from '../../shared/hook-constants.js';
+
+const SUMMARIZE_TIMEOUT_MS = getTimeout(HOOK_TIMEOUTS.DEFAULT);
 
 export const summarizeHandler: EventHandler = {
   async execute(input: NormalizedHookInput): Promise<HookResult> {
@@ -41,15 +43,18 @@ export const summarizeHandler: EventHandler = {
     });
 
     // Send to worker - worker handles privacy check and database operations
-    const response = await fetch(`http://127.0.0.1:${port}/api/sessions/summarize`, {
-      method: 'POST',
-      headers: { 'Content-Type': 'application/json' },
-      body: JSON.stringify({
-        contentSessionId: sessionId,
-        last_assistant_message: lastAssistantMessage
-      })
-      // Note: Removed signal to avoid Windows Bun cleanup issue (libuv assertion)
-    });
+    const response = await fetchWithTimeout(
+      `http://127.0.0.1:${port}/api/sessions/summarize`,
+      {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({
+          contentSessionId: sessionId,
+          last_assistant_message: lastAssistantMessage
+        }),
+      },
+      SUMMARIZE_TIMEOUT_MS
+    );
 
     if (!response.ok) {
       // Return standard response even on failure (matches original behavior)

src/cli/handlers/user-message.ts

@@ -1,8 +1,8 @@
 /**
  * User Message Handler - SessionStart (parallel)
  *
- * Extracted from user-message-hook.ts - displays context info to user via stderr.
- * Uses exit code 3 to show user message without injecting into Claude's context.
+ * Displays context info to user via stderr.
+ * Uses exit code 0 (SUCCESS) - stderr is not shown to Claude with exit 0.
  */
 
 import { basename } from 'path';
@@ -13,34 +13,46 @@ import { HOOK_EXIT_CODES } from '../../shared/hook-constants.js';
 export const userMessageHandler: EventHandler = {
   async execute(input: NormalizedHookInput): Promise<HookResult> {
     // Ensure worker is running
-    await ensureWorkerRunning();
+    const workerReady = await ensureWorkerRunning();
+    if (!workerReady) {
+      // Worker not available — skip user message gracefully
+      return { exitCode: HOOK_EXIT_CODES.SUCCESS };
+    }
 
     const port = getWorkerPort();
     const project = basename(input.cwd ?? process.cwd());
 
     // Fetch formatted context directly from worker API
     // Note: Removed AbortSignal.timeout to avoid Windows Bun cleanup issue (libuv assertion)
-    const response = await fetch(
-      `http://127.0.0.1:${port}/api/context/inject?project=${encodeURIComponent(project)}&colors=true`,
-      { method: 'GET' }
-    );
+    try {
+      const response = await fetch(
+        `http://127.0.0.1:${port}/api/context/inject?project=${encodeURIComponent(project)}&colors=true`,
+        { method: 'GET' }
+      );
 
-    if (!response.ok) {
-      throw new Error(`Failed to fetch context: ${response.status}`);
+      if (!response.ok) {
+        // Don't throw - context fetch failure should not block the user's prompt
+        return { exitCode: HOOK_EXIT_CODES.SUCCESS };
+      }
+
+      const output = await response.text();
+
+      // Write to stderr for user visibility
+      // Note: Using process.stderr.write instead of console.error to avoid
+      // Claude Code treating this as a hook error. The actual hook output
+      // goes to stdout via hook-command.ts JSON serialization.
+      process.stderr.write(
+        "\n\n" + String.fromCodePoint(0x1F4DD) + " Claude-Mem Context Loaded\n\n" +
+        output +
+        "\n\n" + String.fromCodePoint(0x1F4A1) + " Wrap any message with <private> ... </private> to prevent storing sensitive information.\n" +
+        "\n" + String.fromCodePoint(0x1F4AC) + " Community https://discord.gg/J4wttp9vDu" +
+        `\n` + String.fromCodePoint(0x1F4FA) + ` Watch live in browser http://localhost:${port}/\n`
+      );
+    } catch (error) {
+      // Worker unreachable — skip user message gracefully
+      // User message context error is non-critical — skip gracefully
     }
 
-    const output = await response.text();
-
-    // Write to stderr for user visibility (Claude Code UI shows stderr)
-    console.error(
-      "\n\n" + String.fromCodePoint(0x1F4DD) + " Claude-Mem Context Loaded\n" +
-      "   " + String.fromCodePoint(0x2139, 0xFE0F) + "  Note: This appears as stderr but is informational only\n\n" +
-      output +
-      "\n\n" + String.fromCodePoint(0x1F4A1) + " New! Wrap all or part of any message with <private> ... </private> to prevent storing sensitive information in your observation history.\n" +
-      "\n" + String.fromCodePoint(0x1F4AC) + " Community https://discord.gg/J4wttp9vDu" +
-      `\n` + String.fromCodePoint(0x1F4FA) + ` Watch live in browser http://localhost:${port}/\n`
-    );
-
-    return { exitCode: HOOK_EXIT_CODES.USER_MESSAGE_ONLY };
+    return { exitCode: HOOK_EXIT_CODES.SUCCESS };
   }
 };

src/cli/hook-command.ts

@@ -8,6 +8,62 @@ export interface HookCommandOptions {
   skipExit?: boolean;
 }
 
+/**
+ * Classify whether an error indicates the worker is unavailable (graceful degradation)
+ * vs a handler/client bug (blocking error that developers need to see).
+ *
+ * Exit 0 (graceful degradation):
+ * - Transport failures: ECONNREFUSED, ECONNRESET, EPIPE, ETIMEDOUT, fetch failed
+ * - Timeout errors: timed out, timeout
+ * - Server errors: HTTP 5xx status codes
+ *
+ * Exit 2 (blocking error — handler/client bug):
+ * - HTTP 4xx status codes (bad request, not found, validation error)
+ * - Programming errors (TypeError, ReferenceError, SyntaxError)
+ * - All other unexpected errors
+ */
+export function isWorkerUnavailableError(error: unknown): boolean {
+  const message = error instanceof Error ? error.message : String(error);
+  const lower = message.toLowerCase();
+
+  // Transport failures — worker unreachable
+  const transportPatterns = [
+    'econnrefused',
+    'econnreset',
+    'epipe',
+    'etimedout',
+    'enotfound',
+    'econnaborted',
+    'enetunreach',
+    'ehostunreach',
+    'fetch failed',
+    'unable to connect',
+    'socket hang up',
+  ];
+  if (transportPatterns.some(p => lower.includes(p))) return true;
+
+  // Timeout errors — worker didn't respond in time
+  if (lower.includes('timed out') || lower.includes('timeout')) return true;
+
+  // HTTP 5xx server errors — worker has internal problems
+  if (/failed:\s*5\d{2}/.test(message) || /status[:\s]+5\d{2}/.test(message)) return true;
+
+  // HTTP 429 (rate limit) — treat as transient unavailability, not a bug
+  if (/failed:\s*429/.test(message) || /status[:\s]+429/.test(message)) return true;
+
+  // HTTP 4xx client errors — our bug, NOT worker unavailability
+  if (/failed:\s*4\d{2}/.test(message) || /status[:\s]+4\d{2}/.test(message)) return false;
+
+  // Programming errors — code bugs, not worker unavailability
+  // Note: TypeError('fetch failed') already handled by transport patterns above
+  if (error instanceof TypeError || error instanceof ReferenceError || error instanceof SyntaxError) {
+    return false;
+  }
+
+  // Default: treat unknown errors as blocking (conservative — surface bugs)
+  return false;
+}
+
 export async function hookCommand(platform: string, event: string, options: HookCommandOptions = {}): Promise<number> {
   try {
     const adapter = getPlatformAdapter(platform);
@@ -26,9 +82,17 @@ export async function hookCommand(platform: string, event: string, options: Hook
     }
     return exitCode;
   } catch (error) {
+    if (isWorkerUnavailableError(error)) {
+      // Worker unavailable — degrade gracefully, don't block the user
+      console.error(`[claude-mem] Worker unavailable, skipping hook: ${error instanceof Error ? error.message : error}`);
+      if (!options.skipExit) {
+        process.exit(HOOK_EXIT_CODES.SUCCESS);  // = 0 (graceful)
+      }
+      return HOOK_EXIT_CODES.SUCCESS;
+    }
+
+    // Handler/client bug — show as blocking error so developers see it
     console.error(`Hook error: ${error}`);
-    // Use exit code 2 (blocking error) so users see the error message
-    // Exit code 1 only shows in verbose mode per Claude Code docs
     if (!options.skipExit) {
       process.exit(HOOK_EXIT_CODES.BLOCKING_ERROR);  // = 2
     }

src/cli/stdin-reader.ts

@@ -1,16 +1,178 @@
-// Stdin reading utility extracted from hook patterns
-// See src/hooks/save-hook.ts for the original pattern
+// Stdin reading utility for Claude Code hooks
+//
+// Problem: Claude Code doesn't close stdin after writing hook input,
+// so stdin.on('end') never fires and hooks hang indefinitely (#727).
+//
+// Solution: JSON is self-delimiting. We detect complete JSON by attempting
+// to parse after each chunk. Once we have valid JSON, we resolve immediately
+// without waiting for EOF. This is the proper fix, not a timeout workaround.
+
+/**
+ * Check if stdin is available and readable.
+ *
+ * Bun has a bug where accessing process.stdin can crash with EINVAL
+ * if Claude Code doesn't provide a valid stdin file descriptor (#646).
+ * This function safely checks if stdin is usable.
+ */
+function isStdinAvailable(): boolean {
+  try {
+    const stdin = process.stdin;
+
+    // If stdin is a TTY, we're running interactively (not from Claude Code hook)
+    if (stdin.isTTY) {
+      return false;
+    }
+
+    // Accessing stdin.readable triggers Bun's lazy initialization.
+    // If we get here without throwing, stdin is available.
+    // Note: We don't check the value since Node/Bun don't reliably set it to false.
+    // eslint-disable-next-line @typescript-eslint/no-unused-expressions
+    stdin.readable;
+    return true;
+  } catch {
+    // Bun crashed trying to access stdin (EINVAL from fstat)
+    // This is expected when Claude Code doesn't provide valid stdin
+    return false;
+  }
+}
+
+/**
+ * Try to parse the accumulated input as JSON.
+ * Returns the parsed value if successful, undefined if incomplete/invalid.
+ */
+function tryParseJson(input: string): { success: true; value: unknown } | { success: false } {
+  const trimmed = input.trim();
+  if (!trimmed) {
+    return { success: false };
+  }
+
+  try {
+    const value = JSON.parse(trimmed);
+    return { success: true, value };
+  } catch {
+    // JSON is incomplete or invalid
+    return { success: false };
+  }
+}
+
+// Safety timeout - only kicks in if JSON never completes (malformed input).
+// This should rarely/never be hit in normal operation since we detect complete JSON.
+const SAFETY_TIMEOUT_MS = 30000;
+
+// Short delay after last data chunk to try parsing
+// This handles the case where JSON arrives in multiple chunks
+const PARSE_DELAY_MS = 50;
 
 export async function readJsonFromStdin(): Promise<unknown> {
+  // First, check if stdin is even available
+  // This catches the Bun EINVAL crash from issue #646
+  if (!isStdinAvailable()) {
+    return undefined;
+  }
+
   return new Promise((resolve, reject) => {
     let input = '';
-    process.stdin.on('data', (chunk) => input += chunk);
-    process.stdin.on('end', () => {
+    let resolved = false;
+    let parseDelayId: ReturnType<typeof setTimeout> | null = null;
+
+    const cleanup = () => {
       try {
-        resolve(input.trim() ? JSON.parse(input) : undefined);
-      } catch (e) {
-        reject(new Error(`Failed to parse hook input: ${e}`));
+        process.stdin.removeAllListeners('data');
+        process.stdin.removeAllListeners('end');
+        process.stdin.removeAllListeners('error');
+      } catch {
+        // Ignore cleanup errors
       }
-    });
+    };
+
+    const resolveWith = (value: unknown) => {
+      if (resolved) return;
+      resolved = true;
+      if (parseDelayId) clearTimeout(parseDelayId);
+      clearTimeout(safetyTimeoutId);
+      cleanup();
+      resolve(value);
+    };
+
+    const rejectWith = (error: Error) => {
+      if (resolved) return;
+      resolved = true;
+      if (parseDelayId) clearTimeout(parseDelayId);
+      clearTimeout(safetyTimeoutId);
+      cleanup();
+      reject(error);
+    };
+
+    const tryResolveWithJson = () => {
+      const result = tryParseJson(input);
+      if (result.success) {
+        resolveWith(result.value);
+        return true;
+      }
+      return false;
+    };
+
+    // Safety timeout - fallback if JSON never completes
+    const safetyTimeoutId = setTimeout(() => {
+      if (!resolved) {
+        // Try one final parse attempt
+        if (!tryResolveWithJson()) {
+          // If we have data but it's not valid JSON, that's an error
+          if (input.trim()) {
+            rejectWith(new Error(`Incomplete JSON after ${SAFETY_TIMEOUT_MS}ms: ${input.slice(0, 100)}...`));
+          } else {
+            // No data received - resolve with undefined
+            resolveWith(undefined);
+          }
+        }
+      }
+    }, SAFETY_TIMEOUT_MS);
+
+    try {
+      process.stdin.on('data', (chunk) => {
+        input += chunk;
+
+        // Clear any pending parse delay
+        if (parseDelayId) {
+          clearTimeout(parseDelayId);
+          parseDelayId = null;
+        }
+
+        // Try to parse immediately - if JSON is complete, resolve now
+        if (tryResolveWithJson()) {
+          return;
+        }
+
+        // If immediate parse failed, set a short delay and try again
+        // This handles multi-chunk delivery where the last chunk completes the JSON
+        parseDelayId = setTimeout(() => {
+          tryResolveWithJson();
+        }, PARSE_DELAY_MS);
+      });
+
+      process.stdin.on('end', () => {
+        // stdin closed - parse whatever we have
+        if (!resolved) {
+          if (!tryResolveWithJson()) {
+            // Empty or invalid - resolve with undefined
+            resolveWith(input.trim() ? undefined : undefined);
+          }
+        }
+      });
+
+      process.stdin.on('error', () => {
+        if (!resolved) {
+          // Don't reject on stdin errors - just return undefined
+          // This is more graceful for hook execution
+          resolveWith(undefined);
+        }
+      });
+    } catch {
+      // If attaching listeners fails (Bun stdin issue), resolve with undefined
+      resolved = true;
+      clearTimeout(safetyTimeoutId);
+      cleanup();
+      resolve(undefined);
+    }
   });
 }

src/sdk/parser.ts

@@ -162,9 +162,13 @@ export function parseSummary(text: string, sessionId?: number): ParsedSummary |
 /**
  * Extract a simple field value from XML content
  * Returns null for missing or empty/whitespace-only fields
+ *
+ * Uses non-greedy match to handle nested tags and code snippets (Issue #798)
  */
 function extractField(content: string, fieldName: string): string | null {
-  const regex = new RegExp(`<${fieldName}>([^<]*)</${fieldName}>`);
+  // Use [\s\S]*? to match any character including newlines, non-greedily
+  // This handles nested XML tags like <item>...</item> inside the field
+  const regex = new RegExp(`<${fieldName}>([\\s\\S]*?)</${fieldName}>`);
   const match = regex.exec(content);
   if (!match) return null;
 
@@ -174,12 +178,13 @@ function extractField(content: string, fieldName: string): string | null {
 
 /**
  * Extract array of elements from XML content
+ * Handles nested tags and code snippets (Issue #798)
  */
 function extractArrayElements(content: string, arrayName: string, elementName: string): string[] {
   const elements: string[] = [];
 
-  // Match the array block
-  const arrayRegex = new RegExp(`<${arrayName}>(.*?)</${arrayName}>`, 's');
+  // Match the array block using [\s\S]*? for nested content
+  const arrayRegex = new RegExp(`<${arrayName}>([\\s\\S]*?)</${arrayName}>`);
   const arrayMatch = arrayRegex.exec(content);
 
   if (!arrayMatch) {
@@ -188,11 +193,14 @@ function extractArrayElements(content: string, arrayName: string, elementName: s
 
   const arrayContent = arrayMatch[1];
 
-  // Extract individual elements
-  const elementRegex = new RegExp(`<${elementName}>([^<]+)</${elementName}>`, 'g');
+  // Extract individual elements using [\s\S]*? for nested content
+  const elementRegex = new RegExp(`<${elementName}>([\\s\\S]*?)</${elementName}>`, 'g');
   let elementMatch;
   while ((elementMatch = elementRegex.exec(arrayContent)) !== null) {
-    elements.push(elementMatch[1].trim());
+    const trimmed = elementMatch[1].trim();
+    if (trimmed) {
+      elements.push(trimmed);
+    }
   }
 
   return elements;

src/servers/mcp-server.ts

@@ -233,6 +233,31 @@ NEVER fetch full details without filtering first. 10x token savings.`,
     handler: async (args: any) => {
       return await callWorkerAPIPost('/api/observations/batch', args);
     }
+  },
+  {
+    name: 'save_memory',
+    description: 'Save a manual memory/observation for semantic search. Use this to remember important information.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        text: {
+          type: 'string',
+          description: 'Content to remember (required)'
+        },
+        title: {
+          type: 'string',
+          description: 'Short title (auto-generated from text if omitted)'
+        },
+        project: {
+          type: 'string',
+          description: 'Project name (uses "claude-mem" if omitted)'
+        }
+      },
+      required: ['text']
+    },
+    handler: async (args: any) => {
+      return await callWorkerAPIPost('/api/memory/save', args);
+    }
   }
 ];
 

src/services/context/ObservationCompiler.ts

@@ -5,10 +5,10 @@
  */
 
 import path from 'path';
-import { homedir } from 'os';
 import { existsSync, readFileSync } from 'fs';
 import { SessionStore } from '../sqlite/SessionStore.js';
 import { logger } from '../../utils/logger.js';
+import { CLAUDE_CONFIG_DIR } from '../../shared/paths.js';
 import type {
   ContextConfig,
   Observation,
@@ -203,7 +203,8 @@ export function getPriorSessionMessages(
 
   const priorSessionId = priorSessionObs.memory_session_id;
   const dashedCwd = cwdToDashed(cwd);
-  const transcriptPath = path.join(homedir(), '.claude', 'projects', dashedCwd, `${priorSessionId}.jsonl`);
+  // Use CLAUDE_CONFIG_DIR to support custom Claude config directories
+  const transcriptPath = path.join(CLAUDE_CONFIG_DIR, 'projects', dashedCwd, `${priorSessionId}.jsonl`);
   return extractPriorMessages(transcriptPath);
 }
 

src/services/infrastructure/HealthMonitor.ts

@@ -10,9 +10,9 @@
  */
 
 import path from 'path';
-import { homedir } from 'os';
 import { readFileSync } from 'fs';
 import { logger } from '../../utils/logger.js';
+import { MARKETPLACE_ROOT } from '../../shared/paths.js';
 
 /**
  * Check if a port is in use by querying the health endpoint
@@ -100,8 +100,7 @@ export async function httpShutdown(port: number): Promise<boolean> {
  * This is the "expected" version that should be running
  */
 export function getInstalledPluginVersion(): string {
-  const marketplaceRoot = path.join(homedir(), '.claude', 'plugins', 'marketplaces', 'thedotmack');
-  const packageJsonPath = path.join(marketplaceRoot, 'package.json');
+  const packageJsonPath = path.join(MARKETPLACE_ROOT, 'package.json');
   const packageJson = JSON.parse(readFileSync(packageJsonPath, 'utf-8'));
   return packageJson.version;
 }

src/services/infrastructure/ProcessManager.ts

@@ -22,6 +22,17 @@ const execAsync = promisify(exec);
 const DATA_DIR = path.join(homedir(), '.claude-mem');
 const PID_FILE = path.join(DATA_DIR, 'worker.pid');
 
+// Orphaned process cleanup patterns and thresholds
+// These are claude-mem processes that can accumulate if not properly terminated
+const ORPHAN_PROCESS_PATTERNS = [
+  'mcp-server.cjs',    // Main MCP server process
+  'worker-service.cjs', // Background worker daemon
+  'chroma-mcp'          // ChromaDB MCP subprocess
+];
+
+// Only kill processes older than this to avoid killing the current session
+const ORPHAN_MAX_AGE_MINUTES = 30;
+
 export interface PidInfo {
   pid: number;
   port: number;
@@ -66,7 +77,11 @@ export function removePidFile(): void {
 }
 
 /**
- * Get platform-adjusted timeout (Windows socket cleanup is slower)
+ * Get platform-adjusted timeout for worker-side socket operations (2.0x on Windows).
+ *
+ * Note: Two platform multiplier functions exist intentionally:
+ * - getTimeout() in hook-constants.ts uses 1.5x for hook-side operations (fast path)
+ * - getPlatformTimeout() here uses 2.0x for worker-side socket operations (slower path)
  */
 export function getPlatformTimeout(baseMs: number): number {
   const WINDOWS_MULTIPLIER = 2.0;
@@ -90,7 +105,7 @@ export async function getChildProcesses(parentPid: number): Promise<number[]> {
 
   try {
     // PowerShell Get-Process instead of WMIC (deprecated in Windows 11)
-    const cmd = `powershell -NoProfile -NonInteractive -Command "Get-Process | Where-Object { \\$_.ParentProcessId -eq ${parentPid} } | Select-Object -ExpandProperty Id"`;
+    const cmd = `powershell -NoProfile -NonInteractive -Command "Get-Process | Where-Object { $_.ParentProcessId -eq ${parentPid} } | Select-Object -ExpandProperty Id"`;
     const { stdout } = await execAsync(cmd, { timeout: HOOK_TIMEOUTS.POWERSHELL_COMMAND });
     // PowerShell outputs just numbers (one per line), simpler than WMIC's "ProcessId=1234" format
     return stdout
@@ -162,55 +177,119 @@ export async function waitForProcessesExit(pids: number[], timeoutMs: number): P
 }
 
 /**
- * Clean up orphaned chroma-mcp processes from previous worker sessions
- * Prevents process accumulation and memory leaks
+ * Parse process elapsed time from ps etime format: [[DD-]HH:]MM:SS
+ * Returns age in minutes, or -1 if parsing fails
+ */
+export function parseElapsedTime(etime: string): number {
+  if (!etime || etime.trim() === '') return -1;
+
+  const cleaned = etime.trim();
+  let totalMinutes = 0;
+
+  // DD-HH:MM:SS format
+  const dayMatch = cleaned.match(/^(\d+)-(\d+):(\d+):(\d+)$/);
+  if (dayMatch) {
+    totalMinutes = parseInt(dayMatch[1], 10) * 24 * 60 +
+                   parseInt(dayMatch[2], 10) * 60 +
+                   parseInt(dayMatch[3], 10);
+    return totalMinutes;
+  }
+
+  // HH:MM:SS format
+  const hourMatch = cleaned.match(/^(\d+):(\d+):(\d+)$/);
+  if (hourMatch) {
+    totalMinutes = parseInt(hourMatch[1], 10) * 60 + parseInt(hourMatch[2], 10);
+    return totalMinutes;
+  }
+
+  // MM:SS format
+  const minMatch = cleaned.match(/^(\d+):(\d+)$/);
+  if (minMatch) {
+    return parseInt(minMatch[1], 10);
+  }
+
+  return -1;
+}
+
+/**
+ * Clean up orphaned claude-mem processes from previous worker sessions
+ *
+ * Targets mcp-server.cjs, worker-service.cjs, and chroma-mcp processes
+ * that survived a previous daemon crash. Only kills processes older than
+ * ORPHAN_MAX_AGE_MINUTES to avoid killing the current session.
+ *
+ * The periodic ProcessRegistry reaper handles in-session orphans;
+ * this function handles cross-session orphans at startup.
  */
 export async function cleanupOrphanedProcesses(): Promise<void> {
   const isWindows = process.platform === 'win32';
-  const pids: number[] = [];
+  const currentPid = process.pid;
+  const pidsToKill: number[] = [];
 
   try {
     if (isWindows) {
-      // Windows: Use PowerShell Get-CimInstance instead of WMIC (deprecated in Windows 11)
-      const cmd = `powershell -NoProfile -NonInteractive -Command "Get-CimInstance Win32_Process | Where-Object { \\$_.Name -like '*python*' -and \\$_.CommandLine -like '*chroma-mcp*' } | Select-Object -ExpandProperty ProcessId"`;
+      // Windows: Use PowerShell Get-CimInstance with JSON output for age filtering
+      const patternConditions = ORPHAN_PROCESS_PATTERNS
+        .map(p => `$_.CommandLine -like '*${p}*'`)
+        .join(' -or ');
+
+      const cmd = `powershell -NoProfile -NonInteractive -Command "Get-CimInstance Win32_Process | Where-Object { (${patternConditions}) -and $_.ProcessId -ne ${currentPid} } | Select-Object ProcessId, CreationDate | ConvertTo-Json"`;
       const { stdout } = await execAsync(cmd, { timeout: HOOK_TIMEOUTS.POWERSHELL_COMMAND });
 
-      if (!stdout.trim()) {
-        logger.debug('SYSTEM', 'No orphaned chroma-mcp processes found (Windows)');
+      if (!stdout.trim() || stdout.trim() === 'null') {
+        logger.debug('SYSTEM', 'No orphaned claude-mem processes found (Windows)');
         return;
       }
 
-      // PowerShell outputs just numbers (one per line), simpler than WMIC's "ProcessId=1234" format
-      const lines = stdout
-        .split('\n')
-        .map(line => line.trim())
-        .filter(line => line.length > 0 && /^\d+$/.test(line));
+      const processes = JSON.parse(stdout);
+      const processList = Array.isArray(processes) ? processes : [processes];
+      const now = Date.now();
 
-      for (const line of lines) {
-        const pid = parseInt(line, 10);
-        // SECURITY: Validate PID is positive integer before adding to list
-        if (!isNaN(pid) && Number.isInteger(pid) && pid > 0) {
-          pids.push(pid);
+      for (const proc of processList) {
+        const pid = proc.ProcessId;
+        // SECURITY: Validate PID is positive integer and not current process
+        if (!Number.isInteger(pid) || pid <= 0 || pid === currentPid) continue;
+
+        // Parse Windows WMI date format: /Date(1234567890123)/
+        const creationMatch = proc.CreationDate?.match(/\/Date\((\d+)\)\//);
+        if (creationMatch) {
+          const creationTime = parseInt(creationMatch[1], 10);
+          const ageMinutes = (now - creationTime) / (1000 * 60);
+
+          if (ageMinutes >= ORPHAN_MAX_AGE_MINUTES) {
+            pidsToKill.push(pid);
+            logger.debug('SYSTEM', 'Found orphaned process', { pid, ageMinutes: Math.round(ageMinutes) });
+          }
         }
       }
     } else {
-      // Unix: Use ps aux | grep
-      const { stdout } = await execAsync('ps aux | grep "chroma-mcp" | grep -v grep || true');
+      // Unix: Use ps with elapsed time for age-based filtering
+      const patternRegex = ORPHAN_PROCESS_PATTERNS.join('|');
+      const { stdout } = await execAsync(
+        `ps -eo pid,etime,command | grep -E "${patternRegex}" | grep -v grep || true`
+      );
 
       if (!stdout.trim()) {
-        logger.debug('SYSTEM', 'No orphaned chroma-mcp processes found (Unix)');
+        logger.debug('SYSTEM', 'No orphaned claude-mem processes found (Unix)');
         return;
       }
 
       const lines = stdout.trim().split('\n');
       for (const line of lines) {
-        const parts = line.trim().split(/\s+/);
-        if (parts.length > 1) {
-          const pid = parseInt(parts[1], 10);
-          // SECURITY: Validate PID is positive integer before adding to list
-          if (!isNaN(pid) && Number.isInteger(pid) && pid > 0) {
-            pids.push(pid);
-          }
+        // Parse: "  1234  01:23:45 /path/to/process"
+        const match = line.trim().match(/^(\d+)\s+(\S+)\s+(.*)$/);
+        if (!match) continue;
+
+        const pid = parseInt(match[1], 10);
+        const etime = match[2];
+
+        // SECURITY: Validate PID is positive integer and not current process
+        if (!Number.isInteger(pid) || pid <= 0 || pid === currentPid) continue;
+
+        const ageMinutes = parseElapsedTime(etime);
+        if (ageMinutes >= ORPHAN_MAX_AGE_MINUTES) {
+          pidsToKill.push(pid);
+          logger.debug('SYSTEM', 'Found orphaned process', { pid, ageMinutes, command: match[3].substring(0, 80) });
         }
       }
     }
@@ -220,19 +299,20 @@ export async function cleanupOrphanedProcesses(): Promise<void> {
     return;
   }
 
-  if (pids.length === 0) {
+  if (pidsToKill.length === 0) {
     return;
   }
 
-  logger.info('SYSTEM', 'Cleaning up orphaned chroma-mcp processes', {
+  logger.info('SYSTEM', 'Cleaning up orphaned claude-mem processes', {
     platform: isWindows ? 'Windows' : 'Unix',
-    count: pids.length,
-    pids
+    count: pidsToKill.length,
+    pids: pidsToKill,
+    maxAgeMinutes: ORPHAN_MAX_AGE_MINUTES
   });
 
   // Kill all found processes
   if (isWindows) {
-    for (const pid of pids) {
+    for (const pid of pidsToKill) {
       // SECURITY: Double-check PID validation before using in taskkill command
       if (!Number.isInteger(pid) || pid <= 0) {
         logger.warn('SYSTEM', 'Skipping invalid PID', { pid });
@@ -246,7 +326,7 @@ export async function cleanupOrphanedProcesses(): Promise<void> {
       }
     }
   } else {
-    for (const pid of pids) {
+    for (const pid of pidsToKill) {
       try {
         process.kill(pid, 'SIGKILL');
       } catch (error) {
@@ -256,16 +336,16 @@ export async function cleanupOrphanedProcesses(): Promise<void> {
     }
   }
 
-  logger.info('SYSTEM', 'Orphaned processes cleaned up', { count: pids.length });
+  logger.info('SYSTEM', 'Orphaned processes cleaned up', { count: pidsToKill.length });
 }
 
 /**
  * Spawn a detached daemon process
  * Returns the child PID or undefined if spawn failed
  *
- * On Windows, uses WMIC to spawn a truly independent process that
- * survives parent exit without console popups. WMIC creates processes
- * that are not associated with the parent's console.
+ * On Windows, uses PowerShell Start-Process with -WindowStyle Hidden to spawn
+ * a truly independent process without console popups. Unlike WMIC, PowerShell
+ * inherits environment variables from the parent process.
  *
  * On Unix, uses standard detached spawn.
  *
@@ -285,28 +365,46 @@ export function spawnDaemon(
   };
 
   if (isWindows) {
-    // Use WMIC to spawn a process that's independent of the parent console
-    // This avoids the console popup that occurs with detached: true
-    // Paths must be individually quoted for WMIC when they contain spaces
+    // Use PowerShell Start-Process to spawn a hidden, independent process
+    // Unlike WMIC, PowerShell inherits environment variables from parent
+    // -WindowStyle Hidden prevents console popup
     const execPath = process.execPath;
     const script = scriptPath;
-    // WMIC command format: wmic process call create "\"path1\" \"path2\" args"
-    const command = `wmic process call create "\\"${execPath}\\" \\"${script}\\" --daemon"`;
+    const psCommand = `Start-Process -FilePath '${execPath}' -ArgumentList '${script}','--daemon' -WindowStyle Hidden`;
 
     try {
-      execSync(command, {
+      execSync(`powershell -NoProfile -Command "${psCommand}"`, {
         stdio: 'ignore',
-        windowsHide: true
+        windowsHide: true,
+        env
       });
-      // WMIC returns immediately, we can't get the spawned PID easily
-      // Worker will write its own PID file after listen()
       return 0;
     } catch {
       return undefined;
     }
   }
 
-  // Unix: standard detached spawn
+  // Unix: Use setsid to create a new session, fully detaching from the
+  // controlling terminal. This prevents SIGHUP from reaching the daemon
+  // even if the in-process SIGHUP handler somehow fails (belt-and-suspenders).
+  // Fall back to standard detached spawn if setsid is not available.
+  const setsidPath = '/usr/bin/setsid';
+  if (existsSync(setsidPath)) {
+    const child = spawn(setsidPath, [process.execPath, scriptPath, '--daemon'], {
+      detached: true,
+      stdio: 'ignore',
+      env
+    });
+
+    if (child.pid === undefined) {
+      return undefined;
+    }
+
+    child.unref();
+    return child.pid;
+  }
+
+  // Fallback: standard detached spawn (macOS, systems without setsid)
   const child = spawn(process.execPath, [scriptPath, '--daemon'], {
     detached: true,
     stdio: 'ignore',
@@ -322,6 +420,56 @@ export function spawnDaemon(
   return child.pid;
 }
 
+/**
+ * Check if a process with the given PID is alive.
+ *
+ * Uses the process.kill(pid, 0) idiom: signal 0 doesn't send a signal,
+ * it just checks if the process exists and is reachable.
+ *
+ * EPERM is treated as "alive" because it means the process exists but
+ * belongs to a different user/session (common in multi-user setups).
+ * PID 0 (Windows WMIC sentinel for unknown PID) is treated as alive.
+ */
+export function isProcessAlive(pid: number): boolean {
+  // PID 0 is the Windows WMIC sentinel value — process was spawned but PID unknown
+  if (pid === 0) return true;
+
+  // Invalid PIDs are not alive
+  if (!Number.isInteger(pid) || pid < 0) return false;
+
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (error: unknown) {
+    const code = (error as NodeJS.ErrnoException).code;
+    // EPERM = process exists but different user/session — treat as alive
+    if (code === 'EPERM') return true;
+    // ESRCH = no such process — it's dead
+    return false;
+  }
+}
+
+/**
+ * Read the PID file and remove it if the recorded process is dead (stale).
+ *
+ * This is a cheap operation: one filesystem read + one signal-0 check.
+ * Called at the top of ensureWorkerStarted() to clean up after WSL2
+ * hibernate, OOM kills, or other ungraceful worker deaths.
+ */
+export function cleanStalePidFile(): void {
+  const pidInfo = readPidFile();
+  if (!pidInfo) return;
+
+  if (!isProcessAlive(pidInfo.pid)) {
+    logger.info('SYSTEM', 'Removing stale PID file (worker process is dead)', {
+      pid: pidInfo.pid,
+      port: pidInfo.port,
+      startedAt: pidInfo.startedAt
+    });
+    removePidFile();
+  }
+}
+
 /**
  * Create signal handler factory for graceful shutdown
  * Returns a handler function that can be passed to process.on('SIGTERM') etc.

src/services/integrations/CursorHooksInstaller.ts

@@ -16,6 +16,7 @@ import { exec } from 'child_process';
 import { promisify } from 'util';
 import { logger } from '../../utils/logger.js';
 import { getWorkerPort } from '../../shared/worker-utils.js';
+import { DATA_DIR, MARKETPLACE_ROOT, CLAUDE_CONFIG_DIR } from '../../shared/paths.js';
 import {
   readCursorRegistry as readCursorRegistryFromFile,
   writeCursorRegistry as writeCursorRegistryToFile,
@@ -27,7 +28,6 @@ import type { CursorInstallTarget, CursorHooksJson, CursorMcpConfig, Platform }
 const execAsync = promisify(exec);
 
 // Standard paths
-const DATA_DIR = path.join(homedir(), '.claude-mem');
 const CURSOR_REGISTRY_FILE = path.join(DATA_DIR, 'cursor-projects.json');
 
 // ============================================================================
@@ -128,12 +128,12 @@ export async function updateCursorContextForProject(projectName: string, port: n
 /**
  * Find cursor-hooks directory
  * Searches in order: marketplace install, source repo
- * Checks for both bash (common.sh) and PowerShell (common.ps1) scripts
+ * Checks for hooks.json (unified CLI mode) or legacy shell scripts
  */
 export function findCursorHooksDir(): string | null {
   const possiblePaths = [
     // Marketplace install location
-    path.join(homedir(), '.claude', 'plugins', 'marketplaces', 'thedotmack', 'cursor-hooks'),
+    path.join(MARKETPLACE_ROOT, 'cursor-hooks'),
     // Development/source location (relative to built worker-service.cjs in plugin/scripts/)
     path.join(path.dirname(__filename), '..', '..', 'cursor-hooks'),
     // Alternative dev location
@@ -141,8 +141,10 @@ export function findCursorHooksDir(): string | null {
   ];
 
   for (const p of possiblePaths) {
-    // Check for either bash or PowerShell common script
-    if (existsSync(path.join(p, 'common.sh')) || existsSync(path.join(p, 'common.ps1'))) {
+    // Check for hooks.json (unified CLI mode) or legacy shell scripts
+    if (existsSync(path.join(p, 'hooks.json')) ||
+        existsSync(path.join(p, 'common.sh')) ||
+        existsSync(path.join(p, 'common.ps1'))) {
       return p;
     }
   }
@@ -156,7 +158,7 @@ export function findCursorHooksDir(): string | null {
 export function findMcpServerPath(): string | null {
   const possiblePaths = [
     // Marketplace install location
-    path.join(homedir(), '.claude', 'plugins', 'marketplaces', 'thedotmack', 'plugin', 'scripts', 'mcp-server.cjs'),
+    path.join(MARKETPLACE_ROOT, 'plugin', 'scripts', 'mcp-server.cjs'),
     // Development/source location (relative to built worker-service.cjs in plugin/scripts/)
     path.join(path.dirname(__filename), 'mcp-server.cjs'),
     // Alternative dev location
@@ -178,7 +180,7 @@ export function findMcpServerPath(): string | null {
 export function findWorkerServicePath(): string | null {
   const possiblePaths = [
     // Marketplace install location
-    path.join(homedir(), '.claude', 'plugins', 'marketplaces', 'thedotmack', 'plugin', 'scripts', 'worker-service.cjs'),
+    path.join(MARKETPLACE_ROOT, 'plugin', 'scripts', 'worker-service.cjs'),
     // Development/source location (relative to built worker-service.cjs in plugin/scripts/)
     path.join(path.dirname(__filename), 'worker-service.cjs'),
     // Alternative dev location
@@ -193,6 +195,37 @@ export function findWorkerServicePath(): string | null {
   return null;
 }
 
+/**
+ * Find the Bun executable path
+ * Required because worker-service.cjs uses bun:sqlite which is Bun-specific
+ * Searches common installation locations across platforms
+ */
+export function findBunPath(): string {
+  const possiblePaths = [
+    // Standard user install location (most common)
+    path.join(homedir(), '.bun', 'bin', 'bun'),
+    // Global install locations
+    '/usr/local/bin/bun',
+    '/usr/bin/bun',
+    // Windows locations
+    ...(process.platform === 'win32' ? [
+      path.join(homedir(), '.bun', 'bin', 'bun.exe'),
+      path.join(process.env.LOCALAPPDATA || '', 'bun', 'bun.exe'),
+    ] : []),
+  ];
+
+  for (const p of possiblePaths) {
+    if (p && existsSync(p)) {
+      return p;
+    }
+  }
+
+  // Fallback to 'bun' and hope it's in PATH
+  // This allows the installation to proceed even if we can't find bun
+  // The user will get a clear error when the hook runs if bun isn't available
+  return 'bun';
+}
+
 /**
  * Get the target directory for Cursor hooks based on install target
  */
@@ -312,15 +345,21 @@ export async function installCursorHooks(_sourceDir: string, target: CursorInsta
     // Generate hooks.json with unified CLI commands
     const hooksJsonPath = path.join(targetDir, 'hooks.json');
 
+    // Find bun executable - required because worker-service.cjs uses bun:sqlite
+    const bunPath = findBunPath();
+    const escapedBunPath = bunPath.replace(/\\/g, '\\\\');
+
     // Use the absolute path to worker-service.cjs
     // Escape backslashes for JSON on Windows
     const escapedWorkerPath = workerServicePath.replace(/\\/g, '\\\\');
 
-    // Helper to create hook command using unified CLI
+    // Helper to create hook command using unified CLI with bun runtime
     const makeHookCommand = (command: string) => {
-      return `node "${escapedWorkerPath}" hook cursor ${command}`;
+      return `"${escapedBunPath}" "${escapedWorkerPath}" hook cursor ${command}`;
     };
 
+    console.log(`  Using Bun runtime: ${bunPath}`);
+
     const hooksJson: CursorHooksJson = {
       version: 1,
       hooks: {
@@ -356,7 +395,7 @@ export async function installCursorHooks(_sourceDir: string, target: CursorInsta
 Installation complete!
 
 Hooks installed to: ${targetDir}/hooks.json
-Using unified CLI: node worker-service.cjs hook cursor <command>
+Using unified CLI: bun worker-service.cjs hook cursor <command>
 
 Next steps:
   1. Start claude-mem worker: claude-mem start
@@ -532,7 +571,7 @@ export function checkCursorHooksStatus(): number {
         const firstCommand = hooksContent?.hooks?.beforeSubmitPrompt?.[0]?.command || '';
 
         if (firstCommand.includes('worker-service.cjs') && firstCommand.includes('hook cursor')) {
-          console.log(`   Mode: Unified CLI (node worker-service.cjs)`);
+          console.log(`   Mode: Unified CLI (bun worker-service.cjs)`);
         } else {
           // Detect legacy shell scripts
           const bashScripts = ['session-init.sh', 'context-inject.sh', 'save-observation.sh'];
@@ -596,8 +635,8 @@ export async function detectClaudeCode(): Promise<boolean> {
     logger.debug('SYSTEM', 'Claude CLI not in PATH', {}, error as Error);
   }
 
-  // Check for Claude Code plugin directory
-  const pluginDir = path.join(homedir(), '.claude', 'plugins');
+  // Check for Claude Code plugin directory (respects CLAUDE_CONFIG_DIR)
+  const pluginDir = path.join(CLAUDE_CONFIG_DIR, 'plugins');
   if (existsSync(pluginDir)) {
     return true;
   }