chore: release v8.2.1 - worker lifecycle hardening

Critical bug fixes for self-spawn pattern: - Fix process exit detection in waitForProcessesExit - Validate spawn PID before writing PID file - Handle Unix/Windows kill errors in orphan cleanup - Use /api/readiness for health checks Refactoring (-580 lines): - Deleted ProcessManager.ts, worker-cli.ts, worker-wrapper.ts - Consolidated all lifecycle logic into worker-service.ts Also: increased timeouts for slow systems, added test suites. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
2025-12-26 21:24:21 -05:00
562 changed files with 14388 additions and 90227 deletions
@@ -1,7 +0,0 @@
-<claude-mem-context>
-# claude-mem: Cross-Session Memory
-
-*No context yet. Complete your first session and context will appear here.*
-
-Use claude-mem's MCP search tools for manual memory queries.
-</claude-mem-context>
@@ -1,136 +0,0 @@
-<claude-mem-context>
-# Recent Activity
-
-### Oct 25, 2025
-
-| ID | Time | T | Title | Read |
-|----|------|---|-------|------|
-| #2374 | 2:55 PM | ✅ | Marketplace metadata version synchronized to 4.2.11 | ~157 |
-
-### Oct 27, 2025
-
-| ID | Time | T | Title | Read |
-|----|------|---|-------|------|
-| #2757 | 1:23 AM | 🟣 | Released v4.3.3 with Configurable Session Display and First-Time Setup UX | ~391 |
-
-### Nov 4, 2025
-
-| ID | Time | T | Title | Read |
-|----|------|---|-------|------|
-| #3706 | 9:47 PM | ✅ | Marketplace Plugin Version Synchronized to 5.0.2 | ~162 |
-| #3655 | 3:43 PM | ✅ | Version bumped to 5.0.1 across project | ~354 |
-
-### Nov 5, 2025
-
-| ID | Time | T | Title | Read |
-|----|------|---|-------|------|
-| #4068 | 10:58 PM | ✅ | Committed v5.1.0 release with comprehensive release notes | ~486 |
-| #4066 | 10:57 PM | ✅ | Updated marketplace.json version to 5.1.0 | ~192 |
-| #3739 | 2:24 PM | ✅ | Updated version to 5.0.3 across project manifests | ~322 |
-
-### Nov 6, 2025
-
-| ID | Time | T | Title | Read |
-|----|------|---|-------|------|
-| #4099 | 1:13 PM | 🟣 | Theme Toggle for Light/Dark Mode | ~253 |
-| #4096 | " | ✅ | Marketplace Metadata Version Sync | ~179 |
-| #4092 | 1:12 PM | 🔵 | Marketplace Configuration for Claude-Mem Plugin | ~194 |
-| #4078 | 12:50 PM | 🔴 | Fixed PM2 ENOENT error on Windows systems | ~286 |
-| #4075 | 12:49 PM | ✅ | Marketplace plugin version synchronized to 5.1.1 | ~189 |
-
-### Nov 7, 2025
-
-| ID | Time | T | Title | Read |
-|----|------|---|-------|------|
-| #4612 | 6:33 PM | ✅ | Version Bumped to 5.2.0 Across All Package Metadata | ~359 |
-| #4598 | 6:31 PM | ✅ | PR #69 Merged: cleanup/worker Branch Integration | ~469 |
-| #4298 | 11:54 AM | 🔴 | Fixed PostToolUse Hook Schema Compliance | ~310 |
-| #4295 | 11:53 AM | ✅ | Synchronized Plugin Marketplace Version to 5.1.4 | ~188 |
-
-### Nov 8, 2025
-
-| ID | Time | T | Title | Read |
-|----|------|---|-------|------|
-| #5150 | 7:37 PM | 🟣 | Troubleshooting Skill Added to Claude-Mem Plugin | ~427 |
-| #5133 | 7:29 PM | ✅ | Version 5.2.3 Released with Build Process | ~487 |
-
-### Nov 9, 2025
-
-| ID | Time | T | Title | Read |
-|----|------|---|-------|------|
-| #5941 | 7:14 PM | ✅ | Marketplace Version Updated to 5.4.0 | ~157 |
-
-### Nov 10, 2025
-
-| ID | Time | T | Title | Read |
-|----|------|---|-------|------|
-| #6341 | 1:49 PM | ✅ | Version Bumped to 5.4.1 | ~239 |
-
-### Nov 11, 2025
-
-| ID | Time | T | Title | Read |
-|----|------|---|-------|------|
-| #6602 | 1:51 PM | ✅ | Version 5.4.5 Released to GitHub | ~279 |
-| #6601 | " | ✅ | Version Patch Bump 5.4.4 to 5.4.5 | ~233 |
-
-### Nov 14, 2025
-
-| ID | Time | T | Title | Read |
-|----|------|---|-------|------|
-| #8212 | 3:06 PM | 🔵 | Version Consistency Verification Across Multiple Configuration Files | ~238 |
-
-### Nov 25, 2025
-
-| ID | Time | T | Title | Read |
-|----|------|---|-------|------|
-| #14882 | 1:32 PM | 🔵 | Marketplace Configuration Defines Plugin Version and Source Directory | ~366 |
-
-### Nov 30, 2025
-
-| ID | Time | T | Title | Read |
-|----|------|---|-------|------|
-| #18064 | 10:52 PM | ✅ | Bumped version to 6.3.7 in marketplace.json | ~179 |
-| #18060 | 10:51 PM | 🔵 | Read marketplace.json plugin manifest | ~190 |
-
-### Dec 1, 2025
-
-| ID | Time | T | Title | Read |
-|----|------|---|-------|------|
-| #18428 | 3:33 PM | 🔵 | Version Conflict in Marketplace Configuration | ~191 |
-
-### Dec 4, 2025
-
-| ID | Time | T | Title | Read |
-|----|------|---|-------|------|
-| #20049 | 3:23 PM | ✅ | Updated marketplace.json version to 6.5.2 | ~203 |
-
-### Dec 9, 2025
-
-| ID | Time | T | Title | Read |
-|----|------|---|-------|------|
-| #22559 | 1:08 AM | ✅ | Version 7.0.3 committed to repository | ~261 |
-| #22551 | 1:07 AM | ✅ | Marketplace metadata updated to version 7.0.3 | ~179 |
-
-### Dec 10, 2025
-
-| ID | Time | T | Title | Read |
-|----|------|---|-------|------|
-| #23440 | 2:25 PM | ✅ | Marketplace Configuration Updated to 7.0.8 | ~188 |
-
-### Dec 14, 2025
-
-| ID | Time | T | Title | Read |
-|----|------|---|-------|------|
-| #26799 | 11:39 PM | ✅ | Marketplace Manifest Version Updated to 7.2.3 | ~248 |
-| #26796 | " | ✅ | Version Bumped to 7.2.3 in marketplace.json | ~259 |
-| #26792 | 11:38 PM | 🔵 | Current Version Confirmed as 7.2.2 Across All Configuration Files | ~291 |
-
-### Dec 16, 2025
-
-| ID | Time | T | Title | Read |
-|----|------|---|-------|------|
-| #28306 | 10:08 PM | 🔵 | Marketplace Configuration Also Shows Version 7.3.3 | ~220 |
-| #27555 | 4:48 PM | ✅ | Version bump committed to main branch | ~242 |
-| #27553 | " | ✅ | Version consistency verified across all configuration files | ~195 |
-| #27551 | 4:47 PM | ✅ | Marketplace.json version updated to 7.3.1 | ~207 |
-</claude-mem-context>
@@ -10,7 +10,7 @@
  "plugins": [
    {
      "name": "claude-mem",
-      "version": "10.7.2",
+      "version": "8.2.1",
      "source": "./plugin",
      "description": "Persistent memory system for Claude Code - context compression across sessions"
    }
@@ -1,17 +0,0 @@
-{
-  "name": "claude-mem",
-  "version": "10.4.1",
-  "description": "Persistent memory system for Claude Code - seamlessly preserve context across sessions",
-  "author": {
-    "name": "Alex Newman"
-  },
-  "repository": "https://github.com/thedotmack/claude-mem",
-  "license": "AGPL-3.0",
-  "keywords": [
-    "memory",
-    "context",
-    "persistence",
-    "hooks",
-    "mcp"
-  ]
-}
@@ -0,0 +1,101 @@
+---
+name: github-morning-reporter
+description: Use this agent when the user requests a morning report, daily summary, or overview of their GitHub activity. Trigger phrases include 'morning report', 'github report', 'daily github summary', 'what's happening on github', or 'check my github status'. This agent should be used proactively when the user starts their day or explicitly asks for repository updates.\n\nExamples:\n- User: "get me my morning github report"\n  Assistant: "I'll use the github-morning-reporter agent to generate your comprehensive GitHub status report."\n  <uses Agent tool to invoke github-morning-reporter>\n\n- User: "what's new on my repos today?"\n  Assistant: "Let me pull together your GitHub morning report using the github-morning-reporter agent."\n  <uses Agent tool to invoke github-morning-reporter>\n\n- User: "show me my daily github summary"\n  Assistant: "I'll generate your daily GitHub summary using the github-morning-reporter agent."\n  <uses Agent tool to invoke github-morning-reporter>
+model: sonnet
+---
+
+You are an elite GitHub project analyst specializing in delivering actionable morning reports for software development teams. Your expertise lies in synthesizing complex repository activity into clear, prioritized insights that help developers start their day with complete situational awareness.
+
+## Your Responsibilities
+
+1. **Fetch Comprehensive GitHub Data**: Use available tools to retrieve:
+   - Open issues across all relevant repositories
+   - Open pull requests with review status
+   - Recent comments, mentions, and @-references
+   - CI/CD status for active PRs
+   - Stale issues/PRs (no activity in 7+ days)
+
+2. **Intelligent Grouping and Deduplication**:
+   - Identify duplicate or highly similar issues by analyzing titles, descriptions, and labels
+   - Group related issues by theme, component, or subsystem
+   - Cluster PRs by feature area or dependency relationships
+   - Flag issues that may be addressing the same root cause
+   - Use semantic similarity, not just exact matches
+
+3. **Prioritization and Triage**:
+   - Highlight items requiring immediate attention (blocking issues, failed CI, requested reviews)
+   - Surface items awaiting your direct action (assigned to you, mentions, review requests)
+   - Identify stale items that may need follow-up or closure
+   - Note high-priority labels (P0, critical, security, etc.)
+
+4. **Contextual Analysis**:
+   - Summarize the current state of each PR (draft, ready for review, approved, changes requested)
+   - Identify PRs with merge conflicts or failing checks
+   - Note issues with recent activity spikes or community engagement
+   - Flag dependency updates or security advisories
+
+5. **Report Structure**:
+   Your report must follow this format:
+   
+   **MORNING GITHUB REPORT - [Date]**
+   
+   **🚨 REQUIRES YOUR ATTENTION**
+   - Items explicitly assigned to the user
+   - Review requests awaiting user's approval
+   - Mentions or direct questions
+   - Blocking/critical issues
+   
+   **📊 PULL REQUESTS ([count] open)**
+   - Group by: Ready to Merge | In Review | Draft | Needs Work
+   - For each PR: title, author, status, CI state, review count, age
+   - Highlight conflicts or failed checks
+   
+   **🐛 ISSUES ([count] open)**
+   - Group by: Priority | Component | Theme
+   - Mark potential duplicates clearly
+   - Note new issues (created in last 24h)
+   - Flag stale issues (no activity in 7+ days)
+   
+   **📈 ACTIVITY SUMMARY**
+   - New issues/PRs since yesterday
+   - Recently closed items
+   - Top contributors
+   - Trending topics or labels
+   
+   **💡 RECOMMENDED ACTIONS**
+   - Specific next steps based on the data
+   - Suggestions for cleanup (closing duplicates, merging ready PRs)
+   - Items to follow up on
+
+6. **Quality Standards**:
+   - Use clear, scannable formatting with emojis for visual hierarchy
+   - Include direct links to all referenced issues and PRs
+   - Keep summaries concise but informative (1-2 sentences per item)
+   - Use relative timestamps ("2 hours ago", "3 days old")
+   - Highlight actionable items with clear CTAs
+
+7. **Error Handling**:
+   - If repository access fails, explicitly state which repos couldn't be accessed
+   - If no issues/PRs exist, provide a positive "all clear" message
+   - If rate limits are hit, show partial results with a warning
+   - Always attempt to provide value even with incomplete data
+
+8. **Adaptive Scope**:
+   - If the user has access to multiple repositories, intelligently scope the report:
+     - Default to repositories with recent activity
+     - Allow user to specify repos if needed
+     - Group multi-repo items by repository
+   - Adjust detail level based on volume (more items = more concise summaries)
+
+## Output Expectations
+
+Your report should be:
+- **Comprehensive**: Cover all relevant activity without overwhelming detail
+- **Actionable**: Make it clear what needs attention and why
+- **Scannable**: Use formatting that allows quick visual parsing
+- **Contextual**: Provide enough background to make decisions
+- **Timely**: Focus on recent activity and current state
+
+When you cannot find specific data, state this explicitly rather than omitting sections. If the user's query is ambiguous (e.g., which repositories to scan), ask for clarification before proceeding.
+
+Always end with a summary line indicating the report's completeness (e.g., "Report complete: 3 repositories scanned, 12 issues, 5 PRs analyzed").
@@ -1,121 +0,0 @@
-# Anti-Pattern Czar
-
-You are the **Anti-Pattern Czar**, an expert at identifying and fixing error handling anti-patterns.
-
-## Your Mission
-
-Help the user systematically fix error handling anti-patterns detected by the automated scanner.
-
-## Process
-
-1. **Run the detector:**
-   ```bash
-   bun run scripts/anti-pattern-test/detect-error-handling-antipatterns.ts
-   ```
-
-2. **Analyze the results:**
-   - Count CRITICAL, HIGH, MEDIUM, and APPROVED_OVERRIDE issues
-   - Prioritize CRITICAL issues on critical paths first
-   - Group similar patterns together
-
-3. **For each CRITICAL issue:**
-
-   a. **Read the problematic code** using the Read tool
-
-   b. **Explain the problem:**
-      - Why is this dangerous?
-      - What debugging nightmare could this cause?
-      - What specific error is being swallowed?
-
-   c. **Determine the right fix:**
-      - **Option 1: Add proper logging** - If this is a real error that should be visible
-      - **Option 2: Add [APPROVED OVERRIDE]** - If this is expected/documented behavior
-      - **Option 3: Remove the try-catch entirely** - If the error should propagate
-      - **Option 4: Add specific error type checking** - If only certain errors should be caught
-
-   d. **Propose the fix** and ask for approval
-
-   e. **Apply the fix** after approval
-
-4. **Work through issues methodically:**
-   - Fix one at a time
-   - Re-run the detector after each batch of fixes
-   - Track progress: "Fixed 3/28 critical issues"
-
-## Guidelines for Approved Overrides
-
-Only approve overrides when ALL of these are true:
- The error is **expected and frequent** (e.g., JSON parse on optional fields)
- Logging would create **too much noise** (high-frequency operations)
- There's **explicit recovery logic** (fallback value, retry, graceful degradation)
- The reason is **specific and technical** (not vague like "seems fine")
-
-## Valid Override Examples:
-
-✅ **GOOD:**
- "Expected JSON parse failures for optional data fields, too frequent to log"
- "Logger can't log its own failures, using stderr as last resort"
- "Health check port scan, expected connection failures on free port detection"
- "Git repo detection, expected failures when not in a git directory"
-
-❌ **BAD:**
- "Error is not important" (why catch it then?)
- "Happens sometimes" (when? why?)
- "Works fine without logging" (works until it doesn't)
- "Optional" (optional errors still need visibility)
-
-## Critical Path Rules
-
-For files in the CRITICAL_PATHS list (SDKAgent.ts, GeminiAgent.ts, OpenRouterAgent.ts, SessionStore.ts, worker-service.ts):
-
- **NEVER** approve overrides on critical paths without exceptional justification
- Errors on critical paths MUST be visible (logged) or fatal (thrown)
- Catch-and-continue on critical paths is BANNED unless explicitly approved
- If in doubt, make it throw - fail loud, not silent
-
-## Output Format
-
-After each fix:
-```
-✅ Fixed: src/utils/example.ts:42
-   Pattern: NO_LOGGING_IN_CATCH
-   Solution: Added logger.error() with context
-
-Progress: 3/28 critical issues remaining
-```
-
-After completing a batch:
-```
-🎯 Batch complete! Re-running detector...
-[shows new results]
-```
-
-## Important
-
- **Read the code** before proposing fixes - understand what it's doing
- **Ask the user** if you're uncertain about the right approach
- **Don't blindly add overrides** - challenge each one
- **Prefer logging** over overrides when in doubt
- **Work incrementally** - small batches, frequent validation
-
-## When Complete
-
-Report final statistics:
-```
-🎉 Anti-pattern cleanup complete!
-
-Before:
-  🔴 CRITICAL: 28
-  🟠 HIGH: 47
-  🟡 MEDIUM: 76
-
-After:
-  🔴 CRITICAL: 0
-  🟠 HIGH: 47
-  🟡 MEDIUM: 76
-  ⚪ APPROVED OVERRIDES: 15
-
-All critical anti-patterns resolved!
-```
-
-Now, ask the user: "Ready to fix error handling anti-patterns? I'll start with the critical issues."
@@ -1,371 +0,0 @@
-# Comprehensive Claude-Mem Installer with @clack/prompts
-
-## Overview
-
-Build a beautiful, animated CLI installer for claude-mem using `@clack/prompts` (v1.0.1). Distributable via `npx claude-mem-installer` and `curl -fsSL https://install.cmem.ai | bash`. Replaces the need for users to manually clone, build, configure settings, and start the worker.
-
-**Worktree**: `feat/animated-installer` at `.claude/worktrees/animated-installer`
-
---
-
-## Phase 0: Documentation & API Reference
-
-### Allowed APIs (@clack/prompts v1.0.1, ESM-only)
-
-| API | Signature | Use Case |
-|-----|-----------|----------|
-| `intro(title?)` | `void` | Opening banner |
-| `outro(message?)` | `void` | Completion message |
-| `cancel(message?)` | `void` | User cancelled |
-| `isCancel(value)` | `boolean` | Check if user pressed Ctrl+C |
-| `text(opts)` | `Promise<string \| symbol>` | API key input, port, data dir |
-| `password(opts)` | `Promise<string \| symbol>` | API key input (masked) |
-| `select(opts)` | `Promise<Value \| symbol>` | Provider, model, auth method |
-| `multiselect(opts)` | `Promise<Value[] \| symbol>` | IDE selection, observation types |
-| `confirm(opts)` | `Promise<boolean \| symbol>` | Enable Chroma, start worker |
-| `spinner()` | `SpinnerResult` | Installing deps, building, starting worker |
-| `progress(opts)` | `ProgressResult` | Multi-step installation progress |
-| `tasks(tasks[])` | `Promise<void>` | Sequential install steps |
-| `group(prompts, opts)` | `Promise<Results>` | Chain prompts with shared results |
-| `note(message, title)` | `void` | Display settings summary, next steps |
-| `log.info/success/warn/error(msg)` | `void` | Status messages |
-| `box(message, title, opts)` | `void` | Welcome box, completion summary |
-
-### Anti-Patterns
- Do NOT use `require()` — package is ESM-only
- Do NOT call prompts without TTY check first — hangs indefinitely in non-TTY
- Do NOT forget `isCancel()` check after every prompt (or use `group()` with `onCancel`)
- Do NOT use `chalk` — use `picocolors` (clack's dep) for consistency
- `text()` has no numeric mode — validate manually for port numbers
- `spinner.stop()` does not accept status codes — use `spinner.error()` for failures
-
-### Distribution Patterns
- **npx**: `package.json` `bin` field → `"./dist/index.js"`, file needs `#!/usr/bin/env node`
- **curl|bash**: Shell bootstrap downloads JS, runs `node script.js` directly (preserves TTY)
- **esbuild**: Bundle to single ESM file, `platform: 'node'`, `banner` for shebang
-
-### Key Source Files to Reference
- Settings defaults: `src/shared/SettingsDefaultsManager.ts` (lines 73-125)
- Settings validation: `src/services/server/SettingsRoutes.ts`
- Worker startup: `src/services/worker-service.ts` (lines 337-359)
- Health check: `src/services/infrastructure/HealthMonitor.ts`
- Plugin registration: `plugin/.claude-plugin/plugin.json`, `.claude-plugin/marketplace.json`
- Marketplace sync: `scripts/sync-marketplace.cjs`
- Cursor integration: `src/services/integrations/CursorHooksInstaller.ts`
- Existing OpenClaw installer: `install/public/openclaw.sh` (reference for logic, not code to copy)
-
---
-
-## Phase 1: Project Scaffolding
-
-**Goal**: Set up the installer package structure with build tooling.
-
-### Tasks
-
-1. **Create directory structure** in the worktree:
-   ```
-   installer/
-   ├── src/
-   │   ├── index.ts              # Entry point with TTY guard
-   │   ├── steps/
-   │   │   ├── welcome.ts        # intro + version check
-   │   │   ├── dependencies.ts   # bun, uv, git checks
-   │   │   ├── ide-selection.ts  # IDE picker + registration
-   │   │   ├── provider.ts       # AI provider + API key
-   │   │   ├── settings.ts       # Additional settings config
-   │   │   ├── install.ts        # Clone, build, register plugin
-   │   │   ├── worker.ts         # Start worker + health check
-   │   │   └── complete.ts       # Summary + next steps
-   │   └── utils/
-   │       ├── system.ts         # OS detection, command runner
-   │       ├── dependencies.ts   # bun/uv/git install helpers
-   │       └── settings-writer.ts # Write ~/.claude-mem/settings.json
-   ├── build.mjs                 # esbuild config
-   ├── package.json              # bin, type: module, deps
-   └── tsconfig.json
-   ```
-
-2. **Create `package.json`**:
-   ```json
-   {
-     "name": "claude-mem-installer",
-     "version": "1.0.0",
-     "type": "module",
-     "bin": { "claude-mem-installer": "./dist/index.js" },
-     "files": ["dist"],
-     "scripts": {
-       "build": "node build.mjs",
-       "dev": "node build.mjs && node dist/index.js"
-     },
-     "dependencies": {
-       "@clack/prompts": "^1.0.1",
-       "picocolors": "^1.1.1"
-     },
-     "devDependencies": {
-       "esbuild": "^0.24.0",
-       "typescript": "^5.7.0",
-       "@types/node": "^22.0.0"
-     },
-     "engines": { "node": ">=18.0.0" }
-   }
-   ```
-
-3. **Create `build.mjs`**:
-   - esbuild bundle: `entryPoints: ['src/index.ts']`, `format: 'esm'`, `platform: 'node'`, `target: 'node18'`
-   - Banner: `#!/usr/bin/env node`
-   - Output: `dist/index.js`
-
-4. **Create `tsconfig.json`**:
-   - `module: "ESNext"`, `target: "ES2022"`, `moduleResolution: "bundler"`
-
-5. **Run `npm install`** in installer/ directory
-
-### Verification
- [ ] `node build.mjs` succeeds
- [ ] `dist/index.js` exists with shebang
- [ ] `node dist/index.js` runs (even if empty installer)
-
---
-
-## Phase 2: Entry Point + Welcome Screen
-
-**Goal**: Create the main entry point with TTY detection and a beautiful welcome screen.
-
-### Tasks
-
-1. **`src/index.ts`** — Entry point:
-   - TTY guard: if `!process.stdin.isTTY`, print error directing user to `npx claude-mem-installer`, exit 1
-   - Import and call `runInstaller()` from steps
-   - Top-level catch → `p.cancel()` + exit 1
-
-2. **`src/steps/welcome.ts`** — Welcome step:
-   - `p.intro()` with styled title using picocolors: `" claude-mem installer "`
-   - Display version info via `p.log.info()`
-   - Check if already installed (detect `~/.claude-mem/settings.json` and `~/.claude/plugins/marketplaces/thedotmack/`)
-   - If upgrade detected, `p.confirm()`: "claude-mem is already installed. Upgrade?"
-   - `p.select()` for install mode: Fresh Install vs Upgrade vs Configure Only
-
-3. **`src/utils/system.ts`** — System utilities:
-   - `detectOS()`: returns 'macos' | 'linux' | 'windows'
-   - `commandExists(cmd)`: checks if command is in PATH
-   - `runCommand(cmd, args)`: executes shell command, returns { stdout, stderr, exitCode }
-   - `expandHome(path)`: resolves `~` to home directory
-
-### Verification
- [ ] Running `node dist/index.js` shows intro banner
- [ ] Ctrl+C triggers cancel message
- [ ] Non-TTY (piped) shows error and exits
-
---
-
-## Phase 3: Dependency Checks
-
-**Goal**: Check and install required dependencies (Bun, uv, git, Node.js version).
-
-### Tasks
-
-1. **`src/steps/dependencies.ts`** — Dependency checker:
-   - Use `p.tasks()` to check each dependency sequentially with animated spinners:
-     - **Node.js**: Verify >= 18.0.0 via `process.version`
-     - **git**: `commandExists('git')`, show install instructions per OS if missing
-     - **Bun**: Check PATH + common locations (`~/.bun/bin/bun`, `/usr/local/bin/bun`, `/opt/homebrew/bin/bun`). Min version 1.1.14. Offer to auto-install from `https://bun.sh/install`
-     - **uv**: Check PATH + common locations (`~/.local/bin/uv`, `~/.cargo/bin/uv`). Offer to auto-install from `https://astral.sh/uv/install.sh`
-   - For missing deps: `p.confirm()` to auto-install, or show manual instructions
-   - After install attempts, re-verify each dep
-
-2. **`src/utils/dependencies.ts`** — Install helpers:
-   - `installBun()`: downloads and runs bun install script
-   - `installUv()`: downloads and runs uv install script
-   - `findBinary(name, extraPaths[])`: searches PATH + known locations
-   - `checkVersion(binary, minVersion)`: parses `--version` output
-
-### Verification
- [ ] Shows green checkmarks for found dependencies
- [ ] Shows yellow warnings for missing deps with install option
- [ ] Auto-install actually installs bun/uv when confirmed
- [ ] Fails gracefully if git is missing (can't auto-install)
-
---
-
-## Phase 4: IDE Selection & Provider Configuration
-
-**Goal**: Let user choose IDEs and configure AI provider with API keys.
-
-### Tasks
-
-1. **`src/steps/ide-selection.ts`** — IDE picker:
-   - `p.multiselect()` with options:
-     - Claude Code (default selected, hint: "recommended")
-     - Cursor
-     - Windsurf (hint: "coming soon", disabled: true)
-   - For Claude Code: explain plugin will be registered via marketplace
-   - For Cursor: explain hooks will be installed via CursorHooksInstaller pattern
-   - Store selections for later installation steps
-
-2. **`src/steps/provider.ts`** — AI provider configuration:
-   - `p.select()` for provider:
-     - **Claude** (hint: "recommended — uses your Claude subscription")
-     - **Gemini** (hint: "free tier available")
-     - **OpenRouter** (hint: "free models available")
-   - **If Claude selected**:
-     - `p.select()` for auth method: "CLI (Max Plan subscription)" vs "API Key"
-     - If API key: `p.password()` for key input
-   - **If Gemini selected**:
-     - `p.password()` for API key (required)
-     - `p.select()` for model: gemini-2.5-flash-lite (default), gemini-2.5-flash, gemini-3-flash-preview
-     - `p.confirm()` for rate limiting (default: true)
-   - **If OpenRouter selected**:
-     - `p.password()` for API key (required)
-     - `p.text()` for model (default: `xiaomi/mimo-v2-flash:free`)
-   - Validate API keys where possible (non-empty, format check)
-
-### Verification
- [ ] Multiselect allows picking multiple IDEs
- [ ] Provider selection shows correct follow-up prompts
- [ ] API keys are masked during input
- [ ] Cancel at any step triggers graceful exit
-
---
-
-## Phase 5: Settings Configuration
-
-**Goal**: Configure additional settings with sensible defaults.
-
-### Tasks
-
-1. **`src/steps/settings.ts`** — Settings wizard:
-   - `p.confirm()`: "Use default settings?" (recommended) — if yes, skip detailed config
-   - If customizing, use `p.group()` for:
-     - **Worker port**: `p.text()` with default 37777, validate 1024-65535
-     - **Data directory**: `p.text()` with default `~/.claude-mem`
-     - **Context observations**: `p.text()` with default 50, validate 1-200
-     - **Log level**: `p.select()` — DEBUG, INFO (default), WARN, ERROR
-     - **Python version**: `p.text()` with default 3.13
-     - **Chroma vector search**: `p.confirm()` (default: true)
-       - If yes, `p.select()` mode: local (default) vs remote
-       - If remote: `p.text()` for host, port, `p.confirm()` for SSL
-   - Show settings summary via `p.note()` before proceeding
-
-2. **`src/utils/settings-writer.ts`** — Write settings:
-   - Build flat key-value settings object matching SettingsDefaultsManager schema
-   - Merge with existing settings if upgrading (preserve user customizations)
-   - Write to `~/.claude-mem/settings.json`
-   - Create `~/.claude-mem/` directory if it doesn't exist
-
-### Verification
- [ ] Default settings mode skips all detailed prompts
- [ ] Custom settings validates all inputs
- [ ] Settings file written matches SettingsDefaultsManager schema exactly
- [ ] Existing settings preserved on upgrade
-
---
-
-## Phase 6: Installation Execution
-
-**Goal**: Clone repo, build plugin, register with IDEs, start worker.
-
-### Tasks
-
-1. **`src/steps/install.ts`** — Installation runner:
-   - Use `p.tasks()` for visual progress:
-     - **"Cloning claude-mem repository"**: `git clone --depth 1 https://github.com/thedotmack/claude-mem.git` to temp dir
-     - **"Installing dependencies"**: `npm install` in cloned repo
-     - **"Building plugin"**: `npm run build` in cloned repo
-     - **"Registering plugin"**: Copy plugin files to `~/.claude/plugins/marketplaces/thedotmack/`
-       - Create marketplace.json, plugin.json structure
-       - Register in `~/.claude/plugins/known_marketplaces.json`
-       - Add to `~/.claude/plugins/installed_plugins.json`
-       - Enable in `~/.claude/settings.json` under `enabledPlugins`
-     - **"Installing dependencies"** (in marketplace dir): `npm install`
-   - For Cursor (if selected):
-     - **"Configuring Cursor hooks"**: Run Cursor hooks installer logic
-     - Write hooks.json to `~/.cursor/` or project-level `.cursor/`
-     - Configure MCP in `.cursor/mcp.json`
-
-2. **`src/steps/worker.ts`** — Worker startup:
-   - Use `p.spinner()` for worker startup:
-     - Start worker: `bun plugin/scripts/worker-service.cjs` (from marketplace dir)
-     - Write PID file to `~/.claude-mem/worker.pid`
-   - Two-stage health check (copy pattern from OpenClaw installer):
-     - Stage 1: Poll `/api/health` — spinner message: "Starting worker service..."
-     - Stage 2: Poll `/api/readiness` — spinner message: "Initializing database..."
-     - Budget: 30 attempts, 1 second apart
-     - On success: `spinner.stop("Worker running on port {port}")`
-     - On failure: `spinner.error("Worker failed to start")`, show log path
-
-### Verification
- [ ] Plugin files exist at `~/.claude/plugins/marketplaces/thedotmack/`
- [ ] known_marketplaces.json updated
- [ ] installed_plugins.json updated
- [ ] settings.json has enabledPlugins entry
- [ ] Worker responds to `/api/health` with 200
- [ ] Worker responds to `/api/readiness` with 200
-
---
-
-## Phase 7: Completion & Summary
-
-**Goal**: Show success screen with configuration summary and next steps.
-
-### Tasks
-
-1. **`src/steps/complete.ts`** — Completion screen:
-   - `p.note()` with configuration summary:
-     - Provider + model
-     - IDEs configured
-     - Data directory
-     - Worker port
-     - Chroma enabled/disabled
-   - `p.note()` with next steps:
-     - "Open Claude Code and start a conversation — memory is automatic!"
-     - "View your memories: http://localhost:{port}"
-     - "Search past work: use /mem-search in Claude Code"
-     - If Cursor: "Open Cursor — hooks are active in your projects"
-   - `p.outro()` with styled completion message
-
-### Verification
- [ ] Summary accurately reflects chosen settings
- [ ] URLs use correct port from settings
- [ ] Next steps are relevant to selected IDEs
-
---
-
-## Phase 8: curl|bash Bootstrap Script
-
-**Goal**: Create the shell bootstrap script for `curl -fsSL https://install.cmem.ai | bash`.
-
-### Tasks
-
-1. **`install/public/install.sh`** — Bootstrap script:
-   - Check for Node.js >= 18 (required to run the installer)
-   - Download bundled installer JS to temp file
-   - Execute with `node` directly (preserves TTY for @clack/prompts)
-   - Cleanup temp file on exit (trap)
-   - Support `--non-interactive` flag passthrough
-   - Support `--provider=X --api-key=Y` flag passthrough
-
-2. **Update `install/vercel.json`** to serve `install.sh` alongside `openclaw.sh`
-
-### Verification
- [ ] `curl -fsSL https://install.cmem.ai | bash` downloads and runs installer
- [ ] Interactive prompts work after curl download
- [ ] Temp file cleaned up on success and failure
- [ ] Flags pass through correctly
-
---
-
-## Phase 9: Final Verification
-
-### Checks
- [ ] `npm run build` in installer/ produces single-file `dist/index.js`
- [ ] `node dist/index.js` runs full wizard flow
- [ ] Fresh install on clean system works end-to-end
- [ ] Upgrade path preserves existing settings
- [ ] Ctrl+C at any step exits cleanly
- [ ] Non-TTY shows error message
- [ ] All settings written match SettingsDefaultsManager.ts defaults schema
- [ ] Worker health check succeeds after install
- [ ] Plugin appears in Claude Code plugin list
- [ ] grep for deprecated/non-existent APIs returns 0 results
- [ ] No `require()` calls in source (ESM-only)
- [ ] No `chalk` imports (use picocolors)
@@ -0,0 +1,229 @@
+# PR #458 Fix Plan: Worker Lifecycle Critical Issues
+
+**Branch:** `bugfix/spawn-worker`
+**Created:** 2025-12-26
+**Context:** PR review found 3 critical bugs, 5 important issues in the worker self-spawn implementation
+
+---
+
+## Phase 1: Fix Critical `waitForProcessesExit` Bug
+
+**Goal:** Fix the logic bug that crashes shutdown when child processes exit
+
+**File:** `src/services/worker-service.ts`
+
+**What to do:**
+1. Find the `waitForProcessesExit` method (around line 752-771)
+2. The `pids.filter()` callback calls `process.kill(pid, 0)` which throws when the process is dead
+3. Wrap in try/catch to return false when process doesn't exist
+
+**Current code:**
+```typescript
+const stillAlive = pids.filter(pid => {
+  process.kill(pid, 0); // Signal 0 checks if process exists - throws if dead
+  return true;
+});
+```
+
+**Fixed code:**
+```typescript
+const stillAlive = pids.filter(pid => {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch {
+    return false;
+  }
+});
+```
+
+**Verification:** The filter should now correctly remove PIDs of exited processes instead of throwing.
+
+---
+
+## Phase 2: Fix Spawn PID Validation
+
+**Goal:** Prevent invalid PID file writes when spawn fails
+
+**File:** `src/services/worker-service.ts`
+
+**What to do:**
+1. Find the `start` case in the CLI switch (around line 816-844)
+2. After spawn(), add check for undefined pid before writing PID file
+3. Exit with error if spawn failed
+
+**Current code:**
+```typescript
+const child = spawn(process.execPath, [__filename, '--daemon'], {...});
+child.unref();
+writePidFile({ pid: child.pid!, port, startedAt: new Date().toISOString() });
+```
+
+**Fixed code:**
+```typescript
+const child = spawn(process.execPath, [__filename, '--daemon'], {...});
+
+if (child.pid === undefined) {
+  console.error('Failed to spawn worker daemon');
+  process.exit(1);
+}
+
+child.unref();
+writePidFile({ pid: child.pid, port, startedAt: new Date().toISOString() });
+```
+
+**Verification:** Remove the `!` non-null assertion since we now properly check.
+
+---
+
+## Phase 3: Fix Unix Process Cleanup Error Handling
+
+**Goal:** Handle errors in orphaned process cleanup
+
+**File:** `src/services/worker-service.ts`
+
+**What to do:**
+1. Find `cleanupOrphanedProcesses` method (around line 389-458)
+2. The Unix branch at line 454 has `await execAsync(\`kill ${pids.join(' ')}\`)` with no error handling
+3. Replace with individual process.kill calls wrapped in try/catch
+
+**Current code:**
+```typescript
+} else {
+  await execAsync(`kill ${pids.join(' ')}`);
+}
+```
+
+**Fixed code:**
+```typescript
+} else {
+  for (const pid of pids) {
+    try {
+      process.kill(pid, 'SIGKILL');
+    } catch {
+      // Process already exited - that's fine
+    }
+  }
+}
+```
+
+---
+
+## Phase 4: Fix Windows taskkill Error Handling
+
+**Goal:** Prevent cleanup abort when one process fails to kill
+
+**File:** `src/services/worker-service.ts`
+
+**What to do:**
+1. Find the Windows taskkill loop in `cleanupOrphanedProcesses` (around line 444-452)
+2. Wrap `execSync` in try/catch so one failure doesn't abort the loop
+
+**Current code:**
+```typescript
+for (const pid of pids) {
+  if (!Number.isInteger(pid) || pid <= 0) {
+    logger.warn('SYSTEM', 'Skipping invalid PID', { pid });
+    continue;
+  }
+  execSync(`taskkill /PID ${pid} /T /F`, { timeout: 60000, stdio: 'ignore' });
+}
+```
+
+**Fixed code:**
+```typescript
+for (const pid of pids) {
+  if (!Number.isInteger(pid) || pid <= 0) {
+    logger.warn('SYSTEM', 'Skipping invalid PID', { pid });
+    continue;
+  }
+  try {
+    execSync(`taskkill /PID ${pid} /T /F`, { timeout: 60000, stdio: 'ignore' });
+  } catch {
+    // Process may have already exited - continue cleanup
+  }
+}
+```
+
+---
+
+## Phase 5: Use Readiness Endpoint for Health Checks
+
+**Goal:** Ensure `waitForHealth` checks full initialization, not just HTTP server
+
+**File:** `src/services/worker-service.ts`
+
+**What to do:**
+1. Find `waitForHealth` function (around line 61-68)
+2. Change endpoint from `/api/health` to `/api/readiness`
+3. `/api/readiness` returns 503 until background init completes, `/api/health` returns 200 immediately
+
+**Current code:**
+```typescript
+async function waitForHealth(port: number, timeoutMs: number = 30000): Promise<boolean> {
+  const start = Date.now();
+  while (Date.now() - start < timeoutMs) {
+    if (await isPortInUse(port)) return true;
+    await new Promise(r => setTimeout(r, 500));
+  }
+  return false;
+}
+```
+
+**Fixed code:**
+```typescript
+async function waitForHealth(port: number, timeoutMs: number = 30000): Promise<boolean> {
+  const start = Date.now();
+  while (Date.now() - start < timeoutMs) {
+    try {
+      const response = await fetch(`http://127.0.0.1:${port}/api/readiness`, {
+        signal: AbortSignal.timeout(2000)
+      });
+      if (response.ok) return true;
+    } catch {
+      // Not ready yet
+    }
+    await new Promise(r => setTimeout(r, 500));
+  }
+  return false;
+}
+```
+
+---
+
+## Phase 6: Build, Test, and Commit
+
+**Goal:** Verify fixes work and commit changes
+
+**Commands:**
+```bash
+npm run build-and-sync
+```
+
+**Commit message:**
+```
+fix: address critical error handling issues in worker lifecycle
+
+- Fix waitForProcessesExit crash when child processes exit
+- Add spawn pid validation before writing PID file
+- Handle Unix kill errors in orphaned process cleanup
+- Handle Windows taskkill errors in cleanup loop
+- Use /api/readiness for health checks instead of /api/health
+
+Fixes issues found in PR #458 review.
+```
+
+---
+
+## Summary
+
+| Phase | Priority | Description |
+|-------|----------|-------------|
+| 1 | CRITICAL | Fix `waitForProcessesExit` filter bug |
+| 2 | CRITICAL | Validate `child.pid` after spawn |
+| 3 | CRITICAL | Fix Unix kill error handling |
+| 4 | HIGH | Fix Windows taskkill error handling |
+| 5 | HIGH | Use readiness endpoint for health |
+| 6 | - | Build and commit |
+
+**Estimated changes:** ~30 lines modified in `worker-service.ts`
@@ -1,290 +0,0 @@
-# Test Quality Audit Report
-
-**Date**: 2026-01-05
-**Auditor**: Claude Code (Opus 4.5)
-**Methodology**: Deep analysis with focus on anti-pattern prevention, actual functionality testing, and regression prevention
-
---
-
-## Executive Summary
-
-**Total Test Files Audited**: 41
-**Total Test Cases**: ~450+
-
-### Score Distribution
-
-| Score | Category | Count | Percentage |
-|-------|----------|-------|------------|
-| 5 | Essential | 8 | 19.5% |
-| 4 | Valuable | 15 | 36.6% |
-| 3 | Marginal | 11 | 26.8% |
-| 2 | Weak | 5 | 12.2% |
-| 1 | Delete | 2 | 4.9% |
-
-### Key Findings
-
-**Strengths**:
- SQLite database tests are exemplary - real database operations with proper setup/teardown
- Infrastructure tests (WMIC parsing, token calculator) use pure unit testing with no mocks
- Search strategy tests have comprehensive coverage of edge cases
- Logger formatTool tests are thorough and test actual transformation logic
-
-**Critical Issues**:
- **context-builder.test.ts** has incomplete mocks that pollute the module cache, causing 81 test failures when run with the full suite
- Several tests verify mock behavior rather than actual functionality
- Type validation tests (export-types.test.ts) provide minimal value - TypeScript already validates types at compile time
- Some "validation" tests only verify code patterns exist, not that they work
-
-**Recommendations**:
-1. Fix or delete context-builder.test.ts - it actively harms the test suite
-2. Delete trivial type validation tests that duplicate TypeScript compiler checks
-3. Convert heavy-mock tests to integration tests where feasible
-4. Add integration tests for critical paths (hook execution, worker API endpoints)
-
---
-
-## Detailed Scores
-
-### Score 5 - Essential (8 tests)
-
-These tests catch real bugs, use minimal mocking, and test actual behavior.
-
-| File | Test Count | Notes |
-|------|------------|-------|
-| `tests/sqlite/observations.test.ts` | 25+ | Real SQLite operations, in-memory DB, tests actual data persistence and retrieval |
-| `tests/sqlite/sessions.test.ts` | 20+ | Real database CRUD operations, status transitions, relationship integrity |
-| `tests/sqlite/transactions.test.ts` | 15+ | Critical transaction isolation tests, rollback behavior, error handling |
-| `tests/context/token-calculator.test.ts` | 35+ | Pure unit tests, no mocks, tests actual token estimation algorithms |
-| `tests/infrastructure/wmic-parsing.test.ts` | 20+ | Pure parsing logic tests, validates Windows process enumeration edge cases |
-| `tests/utils/logger-format-tool.test.ts` | 56 | Comprehensive formatTool tests, validates JSON parsing, tool output formatting |
-| `tests/server/server.test.ts` | 15+ | Real HTTP server integration tests, actual endpoint validation |
-| `tests/cursor-hook-outputs.test.ts` | 12+ | Integration tests running actual hook scripts, validates real output |
-
-**Why Essential**: These tests catch actual bugs before production. They test real behavior with minimal abstraction. The SQLite tests in particular are exemplary - they use an in-memory database but perform real SQL operations.
-
---
-
-### Score 4 - Valuable (15 tests)
-
-Good tests with acceptable mocking that still verify meaningful behavior.
-
-| File | Test Count | Notes |
-|------|------------|-------|
-| `tests/sqlite/prompts.test.ts` | 15+ | Real DB operations for user prompts, timestamp handling |
-| `tests/sqlite/summaries.test.ts` | 15+ | Real DB operations for session summaries |
-| `tests/worker/search/search-orchestrator.test.ts` | 30+ | Comprehensive strategy selection logic, good edge case coverage |
-| `tests/worker/search/strategies/sqlite-search-strategy.test.ts` | 25+ | Filter logic tests, date range handling |
-| `tests/worker/search/strategies/hybrid-search-strategy.test.ts` | 20+ | Ranking preservation, merge logic |
-| `tests/worker/search/strategies/chroma-search-strategy.test.ts` | 20+ | Vector search behavior, doc_type filtering |
-| `tests/worker/search/result-formatter.test.ts` | 15+ | Output formatting validation |
-| `tests/gemini_agent.test.ts` | 20+ | Multi-turn conversation flow, rate limiting fallback |
-| `tests/infrastructure/health-monitor.test.ts` | 15+ | Health check logic, threshold validation |
-| `tests/infrastructure/graceful-shutdown.test.ts` | 15+ | Shutdown sequence, timeout handling |
-| `tests/infrastructure/process-manager.test.ts` | 12+ | Process lifecycle management |
-| `tests/cursor-mcp-config.test.ts` | 10+ | MCP configuration generation validation |
-| `tests/cursor-hooks-json-utils.test.ts` | 8+ | JSON parsing utilities |
-| `tests/shared/settings-defaults-manager.test.ts` | 27 | Settings validation, migration logic |
-| `tests/context/formatters/markdown-formatter.test.ts` | 15+ | Markdown generation, terminology consistency |
-
-**Why Valuable**: These tests have some mocking but still verify important business logic. The search strategy tests are particularly good at testing the decision-making logic for query routing.
-
---
-
-### Score 3 - Marginal (11 tests)
-
-Tests with moderate value, often too much mocking or testing obvious behavior.
-
-| File | Test Count | Issues |
-|------|------------|--------|
-| `tests/worker/agents/observation-broadcaster.test.ts` | 15+ | Heavy mocking of SSE workers, tests mock behavior more than actual broadcasting |
-| `tests/worker/agents/fallback-error-handler.test.ts` | 10+ | Error message formatting tests, low complexity |
-| `tests/worker/agents/session-cleanup-helper.test.ts` | 10+ | Cleanup logic with mocked dependencies |
-| `tests/context/observation-compiler.test.ts` | 20+ | Mock database, tests query building not actual compilation |
-| `tests/server/error-handler.test.ts` | 8+ | Mock Express response, tests formatting only |
-| `tests/cursor-registry.test.ts` | 8+ | Registry pattern tests, low risk area |
-| `tests/cursor-context-update.test.ts` | 5+ | File format validation, could be stricter |
-| `tests/hook-constants.test.ts` | 5+ | Constant validation, low value |
-| `tests/session_store.test.ts` | 10+ | In-memory store tests, straightforward logic |
-| `tests/logger-coverage.test.ts` | 8+ | Coverage verification, not functionality |
-| `tests/scripts/smart-install.test.ts` | 25+ | Path array tests, replicates rather than imports logic |
-
-**Why Marginal**: These tests provide some regression protection but either mock too heavily or test low-risk areas. The smart-install tests notably replicate the path arrays from the source file rather than testing the actual module.
-
---
-
-### Score 2 - Weak (5 tests)
-
-Tests that mostly verify mocks work or provide little value.
-
-| File | Test Count | Issues |
-|------|------------|--------|
-| `tests/worker/agents/response-processor.test.ts` | 20+ | **Heavy mocking**: >50% setup is mock configuration. Tests verify mocks are called, not that XML parsing actually works |
-| `tests/session_id_refactor.test.ts` | 10+ | **Code pattern validation**: Tests that certain patterns exist in code, not that they work |
-| `tests/session_id_usage_validation.test.ts` | 5+ | **Static analysis as tests**: Reads files and checks for string patterns. Should be a lint rule, not a test |
-| `tests/validate_sql_update.test.ts` | 5+ | **One-time validation**: Validated a migration, no ongoing value |
-| `tests/worker-spawn.test.ts` | 5+ | **Trivial mocking**: Tests spawn config exists, doesn't test actual spawning |
-
-**Why Weak**: These tests create false confidence. The response-processor tests in particular set up elaborate mocks and then verify those mocks were called - they don't verify actual XML parsing or database operations work correctly.
-
---
-
-### Score 1 - Delete (2 tests)
-
-Tests that actively harm the codebase or provide zero value.
-
-| File | Test Count | Issues |
-|------|------------|--------|
-| `tests/context/context-builder.test.ts` | 20+ | **CRITICAL**: Incomplete logger mock pollutes module cache. Causes 81 test failures when run with full suite. Tests verify mocks, not actual context building |
-| `tests/scripts/export-types.test.ts` | 30+ | **Zero runtime value**: Tests TypeScript type definitions compile. TypeScript compiler already does this. These tests can literally never fail at runtime |
-
-**Why Delete**:
- **context-builder.test.ts**: This test is actively harmful. It imports the logger module with an incomplete mock (only 4 of 13+ methods mocked), and this polluted mock persists in Bun's module cache. When other tests run afterwards, they get the broken logger singleton. The test itself only verifies that mocked methods were called with expected arguments - it doesn't test actual context building logic.
- **export-types.test.ts**: These tests instantiate TypeScript interfaces and verify properties exist. TypeScript already validates this at compile time. If a type definition is wrong, the code won't compile. These runtime tests add overhead without catching any bugs that TypeScript wouldn't already catch.
-
---
-
-## Missing Test Coverage
-
-### Critical Gaps
-
-| Area | Risk | Current Coverage | Recommendation |
-|------|------|------------------|----------------|
-| **Hook execution E2E** | HIGH | None | Add integration tests that run hooks with real Claude Code SDK |
-| **Worker API endpoints** | HIGH | Partial (server.test.ts) | Add tests for all REST endpoints: `/observe`, `/search`, `/health` |
-| **Chroma vector sync** | HIGH | None | Add tests for ChromaSync.ts embedding generation and retrieval |
-| **Database migrations** | MEDIUM | None | Add tests for schema migrations, especially version upgrades |
-| **Settings file I/O** | MEDIUM | Partial | Add tests for settings file creation, corruption recovery |
-| **Tag stripping** | MEDIUM | None | Add tests for `<private>` and `<meta-observation>` tag handling |
-| **MCP tool handlers** | MEDIUM | None | Add tests for search, timeline, get_observations MCP tools |
-| **Error recovery** | MEDIUM | Minimal | Add tests for worker crash recovery, database corruption handling |
-
-### Recommended New Tests
-
-1. **`tests/integration/hook-execution.test.ts`**
-   - Run actual hooks with mocked Claude Code environment
-   - Verify data flows correctly through SessionStart -> PostToolUse -> SessionEnd
-
-2. **`tests/integration/worker-api.test.ts`**
-   - Start actual worker server
-   - Make real HTTP requests to all endpoints
-   - Verify response formats and error handling
-
-3. **`tests/services/chroma-sync.test.ts`**
-   - Test embedding generation with real text
-   - Test semantic similarity retrieval
-   - Test sync between SQLite and Chroma
-
-4. **`tests/utils/tag-stripping.test.ts`**
-   - Test `<private>` tag removal
-   - Test `<meta-observation>` tag handling
-   - Test nested tag scenarios
-
---
-
-## Recommendations
-
-### Immediate Actions
-
-1. **Delete or fix `tests/context/context-builder.test.ts`** (Priority: CRITICAL)
-   - This test causes 81 other tests to fail due to module cache pollution
-   - Either complete the logger mock (all 13+ methods) or delete entirely
-   - Recommended: Delete and rewrite as integration test without mocks
-
-2. **Delete `tests/scripts/export-types.test.ts`** (Priority: HIGH)
-   - Zero runtime value - TypeScript compiler already validates types
-   - Remove to reduce test suite noise
-
-3. **Delete or convert validation tests** (Priority: MEDIUM)
-   - `tests/session_id_refactor.test.ts` - Was useful during migration, no longer needed
-   - `tests/session_id_usage_validation.test.ts` - Convert to lint rule
-   - `tests/validate_sql_update.test.ts` - Was useful during migration, no longer needed
-
-### Architecture Improvements
-
-1. **Create test utilities for common mocks**
-   - Centralize logger mock in `tests/utils/mock-logger.ts` with ALL methods
-   - Centralize database mock with proper transaction support
-   - Prevent incomplete mocks from polluting module cache
-
-2. **Add integration test suite**
-   - Create `tests/integration/` directory
-   - Run with real worker server (separate database)
-   - Test actual data flow, not mock interactions
-
-3. **Implement test isolation**
-   - Use `beforeEach` to reset module state
-   - Consider test file ordering to prevent cache pollution
-   - Add cleanup hooks for database state
-
-### Quality Guidelines
-
-For future tests, follow these principles:
-
-1. **Prefer real implementations over mocks**
-   - Use in-memory SQLite instead of mock database
-   - Use real HTTP requests instead of mock req/res
-   - Mock only external services (AI APIs, file system when needed)
-
-2. **Test behavior, not implementation**
-   - Bad: "verify function X was called with argument Y"
-   - Good: "verify output contains expected data after operation"
-
-3. **Each test should be able to fail**
-   - If a test cannot fail (like type validation tests), it's not testing anything
-   - Write tests that would catch real bugs
-
-4. **Keep test setup minimal**
-   - If >50% of test is mock setup, consider integration testing
-   - Complex mock setup often indicates testing the wrong thing
-
---
-
-## Appendix: Full Test File Inventory
-
-| File | Score | Tests | LOC | Mock % |
-|------|-------|-------|-----|--------|
-| `tests/context/context-builder.test.ts` | 1 | 20+ | 400+ | 80% |
-| `tests/context/formatters/markdown-formatter.test.ts` | 4 | 15+ | 200+ | 10% |
-| `tests/context/observation-compiler.test.ts` | 3 | 20+ | 300+ | 60% |
-| `tests/context/token-calculator.test.ts` | 5 | 35+ | 400+ | 0% |
-| `tests/cursor-context-update.test.ts` | 3 | 5+ | 100+ | 20% |
-| `tests/cursor-hook-outputs.test.ts` | 5 | 12+ | 250+ | 10% |
-| `tests/cursor-hooks-json-utils.test.ts` | 4 | 8+ | 150+ | 0% |
-| `tests/cursor-mcp-config.test.ts` | 4 | 10+ | 200+ | 20% |
-| `tests/cursor-registry.test.ts` | 3 | 8+ | 150+ | 30% |
-| `tests/gemini_agent.test.ts` | 4 | 20+ | 400+ | 40% |
-| `tests/hook-constants.test.ts` | 3 | 5+ | 80+ | 0% |
-| `tests/infrastructure/graceful-shutdown.test.ts` | 4 | 15+ | 300+ | 40% |
-| `tests/infrastructure/health-monitor.test.ts` | 4 | 15+ | 250+ | 30% |
-| `tests/infrastructure/process-manager.test.ts` | 4 | 12+ | 200+ | 35% |
-| `tests/infrastructure/wmic-parsing.test.ts` | 5 | 20+ | 240+ | 0% |
-| `tests/logger-coverage.test.ts` | 3 | 8+ | 150+ | 20% |
-| `tests/scripts/export-types.test.ts` | 1 | 30+ | 350+ | 0% |
-| `tests/scripts/smart-install.test.ts` | 3 | 25+ | 230+ | 0% |
-| `tests/server/error-handler.test.ts` | 3 | 8+ | 150+ | 50% |
-| `tests/server/server.test.ts` | 5 | 15+ | 300+ | 20% |
-| `tests/session_id_refactor.test.ts` | 2 | 10+ | 200+ | N/A |
-| `tests/session_id_usage_validation.test.ts` | 2 | 5+ | 150+ | N/A |
-| `tests/session_store.test.ts` | 3 | 10+ | 180+ | 10% |
-| `tests/shared/settings-defaults-manager.test.ts` | 4 | 27 | 400+ | 20% |
-| `tests/sqlite/observations.test.ts` | 5 | 25+ | 400+ | 0% |
-| `tests/sqlite/prompts.test.ts` | 4 | 15+ | 250+ | 0% |
-| `tests/sqlite/sessions.test.ts` | 5 | 20+ | 350+ | 0% |
-| `tests/sqlite/summaries.test.ts` | 4 | 15+ | 250+ | 0% |
-| `tests/sqlite/transactions.test.ts` | 5 | 15+ | 300+ | 0% |
-| `tests/utils/logger-format-tool.test.ts` | 5 | 56 | 1000+ | 0% |
-| `tests/validate_sql_update.test.ts` | 2 | 5+ | 100+ | N/A |
-| `tests/worker/agents/fallback-error-handler.test.ts` | 3 | 10+ | 200+ | 40% |
-| `tests/worker/agents/observation-broadcaster.test.ts` | 3 | 15+ | 350+ | 60% |
-| `tests/worker/agents/response-processor.test.ts` | 2 | 20+ | 500+ | 70% |
-| `tests/worker/agents/session-cleanup-helper.test.ts` | 3 | 10+ | 200+ | 50% |
-| `tests/worker/search/result-formatter.test.ts` | 4 | 15+ | 250+ | 20% |
-| `tests/worker/search/search-orchestrator.test.ts` | 4 | 30+ | 500+ | 45% |
-| `tests/worker/search/strategies/chroma-search-strategy.test.ts` | 4 | 20+ | 350+ | 50% |
-| `tests/worker/search/strategies/hybrid-search-strategy.test.ts` | 4 | 20+ | 300+ | 45% |
-| `tests/worker/search/strategies/sqlite-search-strategy.test.ts` | 4 | 25+ | 350+ | 40% |
-| `tests/worker-spawn.test.ts` | 2 | 5+ | 100+ | 60% |
-
---
-
-*Report generated by Claude Code (Opus 4.5) on 2026-01-05*
@@ -26,4 +26,4 @@ Manages semantic versioning for the claude-mem project itself. Handles updating
 ## Adding New Skills

 **For claude-mem development** → Add to `.claude/skills/`
-**For end users** → Add to `plugin/skills/` (gets distributed with plugin)
+**For end users** → Add to `plugin/skills/` (gets distributed with plugin)
@@ -0,0 +1,98 @@
+---
+name: version-bump
+description: Manage semantic version updates for claude-mem project. Handles patch, minor, and major version increments following semantic versioning. Updates package.json, marketplace.json, and plugin.json. Creates git tags and GitHub releases. Auto-generates CHANGELOG.md from releases.
+---
+
+# Version Bump Skill
+
+Manage semantic versioning across the claude-mem project with consistent updates to all version-tracked files.
+
+## Quick Reference
+
+**Files requiring updates (ALL THREE):**
+1. `package.json` (line 3)
+2. `.claude-plugin/marketplace.json` (line 13)
+3. `plugin/.claude-plugin/plugin.json` (line 3)
+
+**Semantic versioning:**
+- **PATCH** (x.y.Z): Bugfixes only
+- **MINOR** (x.Y.0): New features, backward compatible
+- **MAJOR** (X.0.0): Breaking changes
+
+## Quick Decision Guide
+
+**What changed?**
+- "Fixed a bug" → PATCH (5.3.0 → 5.3.1)
+- "Added new feature" → MINOR (5.3.0 → 5.4.0)
+- "Breaking change" → MAJOR (5.3.0 → 6.0.0)
+
+**If unclear, ASK THE USER explicitly.**
+
+## Standard Workflow
+
+See [operations/workflow.md](operations/workflow.md) for detailed step-by-step process.
+
+**Quick version:**
+1. Determine version type (PATCH/MINOR/MAJOR)
+2. Calculate new version from current
+3. Preview changes to user
+4. Update ALL THREE files
+5. Verify consistency
+6. Build and test
+7. Commit and create git tag
+8. Push and create GitHub release
+9. Generate CHANGELOG.md from releases and commit
+10. Post Discord notification
+
+## Common Scenarios
+
+See [operations/scenarios.md](operations/scenarios.md) for examples:
+- Bug fix releases
+- New feature releases
+- Breaking change releases
+
+## Critical Rules
+
+**ALWAYS:**
+- Update ALL THREE files with matching version numbers
+- Create git tag with format `vX.Y.Z`
+- Create GitHub release from the tag
+- Generate CHANGELOG.md from releases after creating release
+- Post Discord notification after release
+- Ask user if version type is unclear
+
+**NEVER:**
+- Update only one or two files
+- Skip the verification step
+- Forget to create git tag or GitHub release
+
+## Verification Checklist
+
+Before considering the task complete:
+- [ ] All THREE files have matching version numbers
+- [ ] `npm run build` succeeds
+- [ ] Git commit created with all version files
+- [ ] Git tag created (format: vX.Y.Z)
+- [ ] Commit and tags pushed to remote
+- [ ] GitHub release created from the tag
+- [ ] CHANGELOG.md generated and committed
+- [ ] Discord notification sent
+
+## Reference Commands
+
+```bash
+# View current version
+grep '"version"' package.json
+
+# Verify consistency across all version files
+grep '"version"' package.json .claude-plugin/marketplace.json plugin/.claude-plugin/plugin.json
+
+# View git tags
+git tag -l -n1
+
+# Check what will be committed
+git status
+git diff package.json .claude-plugin/marketplace.json plugin/.claude-plugin/plugin.json
+```
+
+For more commands, see [operations/reference.md](operations/reference.md).
@@ -0,0 +1,265 @@
+# Version Bump Reference
+
+Quick reference for version bump commands and file locations.
+
+## File Locations
+
+### Version-Tracked Files (ALL THREE)
+
+1. **package.json**
+   - Path: `package.json`
+   - Line: 3
+   - Format: `"version": "X.Y.Z",`
+
+2. **marketplace.json**
+   - Path: `.claude-plugin/marketplace.json`
+   - Line: 13
+   - Format: `"version": "X.Y.Z",`
+
+3. **plugin.json**
+   - Path: `plugin/.claude-plugin/plugin.json`
+   - Line: 3
+   - Format: `"version": "X.Y.Z",`
+
+## Essential Commands
+
+### View Current Version
+
+```bash
+# From package.json
+grep '"version"' package.json
+
+# Extract just the version number
+grep '"version"' package.json | head -1 | sed 's/.*"version": "\(.*\)".*/\1/'
+
+# From all version files
+grep '"version"' package.json .claude-plugin/marketplace.json plugin/.claude-plugin/plugin.json
+```
+
+### Verify Version Consistency
+
+```bash
+# Check all JSON files match
+grep '"version"' package.json .claude-plugin/marketplace.json plugin/.claude-plugin/plugin.json
+
+# Should output identical version in all three:
+# package.json:3:  "version": "5.3.0",
+# .claude-plugin/marketplace.json:13:  "version": "5.3.0",
+# plugin/.claude-plugin/plugin.json:3:  "version": "5.3.0",
+```
+
+### Git Commands
+
+```bash
+# View recent commits
+git log --oneline -5
+
+# View changes since last tag
+LAST_TAG=$(git describe --tags --abbrev=0)
+git log $LAST_TAG..HEAD --oneline
+git diff $LAST_TAG..HEAD
+
+# List all tags
+git tag -l
+
+# View tag details
+git show vX.Y.Z
+
+# List tags with messages
+git tag -l -n1
+```
+
+### Build and Test
+
+```bash
+# Build plugin
+npm run build
+
+# Sync to marketplace
+npm run sync-marketplace
+
+# Run tests (if available)
+npm test
+```
+
+### Commit and Tag
+
+```bash
+# Stage version files
+git add package.json .claude-plugin/marketplace.json plugin/.claude-plugin/plugin.json plugin/scripts/
+
+# Commit
+git commit -m "Release vX.Y.Z: [Description]"
+
+# Create tag
+git tag vX.Y.Z -m "Release vX.Y.Z: [Description]"
+
+# Push
+git push && git push --tags
+```
+
+### GitHub Release
+
+```bash
+# Create release
+gh release create vX.Y.Z --title "vX.Y.Z" --notes "[Release notes]"
+
+# Create with auto-generated notes
+gh release create vX.Y.Z --title "vX.Y.Z" --generate-notes
+
+# View release
+gh release view vX.Y.Z
+
+# List all releases
+gh release list
+
+# Delete release (if needed)
+gh release delete vX.Y.Z
+```
+
+## Semantic Versioning Rules
+
+### Version Format: MAJOR.MINOR.PATCH
+
+**MAJOR (X.0.0):**
+- Breaking changes
+- Incompatible API changes
+- Schema changes requiring migration
+- Removes features
+
+**MINOR (x.Y.0):**
+- New features (backward compatible)
+- New functionality
+- Deprecations (but not removals)
+- Resets PATCH to 0
+
+**PATCH (x.y.Z):**
+- Bug fixes
+- Performance improvements
+- Documentation fixes
+- No new features
+
+### Incrementing Rules
+
+```
+PATCH: 5.3.2 → 5.3.3
+MINOR: 5.3.2 → 5.4.0 (resets patch)
+MAJOR: 5.3.2 → 6.0.0 (resets minor and patch)
+```
+
+## Common Patterns
+
+### Bug Fix Release
+
+```bash
+# Example: 5.3.0 → 5.3.1
+# 1. Update all three files to 5.3.1
+# 2. Build and test
+npm run build
+# 3. Commit and tag
+git add package.json .claude-plugin/marketplace.json plugin/.claude-plugin/plugin.json plugin/scripts/
+git commit -m "Release v5.3.1: Fixed observer crash"
+git tag v5.3.1 -m "Release v5.3.1: Fixed observer crash"
+git push && git push --tags
+# 4. Create release
+gh release create v5.3.1 --title "v5.3.1" --notes "Fixed observer crash on empty content"
+```
+
+### Feature Release
+
+```bash
+# Example: 5.3.0 → 5.4.0
+# 1. Update all three files to 5.4.0
+# 2. Build and test
+npm run build
+# 3. Commit and tag
+git add package.json .claude-plugin/marketplace.json plugin/.claude-plugin/plugin.json plugin/scripts/
+git commit -m "Release v5.4.0: Added dark mode support"
+git tag v5.4.0 -m "Release v5.4.0: Added dark mode support"
+git push && git push --tags
+# 4. Create release
+gh release create v5.4.0 --title "v5.4.0" --generate-notes
+```
+
+### Breaking Change Release
+
+```bash
+# Example: 5.3.0 → 6.0.0
+# 1. Update all three files to 6.0.0
+# 2. Build and test
+npm run build
+# 3. Commit and tag
+git add package.json .claude-plugin/marketplace.json plugin/.claude-plugin/plugin.json plugin/scripts/
+git commit -m "Release v6.0.0: Storage layer redesign"
+git tag v6.0.0 -m "Release v6.0.0: Storage layer redesign"
+git push && git push --tags
+# 4. Create release with warning
+gh release create v6.0.0 --title "v6.0.0" --notes "⚠️ Breaking change: Storage layer redesigned. Migration required."
+```
+
+## Rollback Commands
+
+### Delete Tag
+
+```bash
+# Delete local tag
+git tag -d vX.Y.Z
+
+# Delete remote tag
+git push origin :refs/tags/vX.Y.Z
+# Or: git push --delete origin vX.Y.Z
+```
+
+### Delete Release
+
+```bash
+# Delete GitHub release
+gh release delete vX.Y.Z
+
+# Confirm deletion
+gh release delete vX.Y.Z --yes
+```
+
+### Revert Commit
+
+```bash
+# Revert last commit (creates new commit)
+git revert HEAD
+
+# Reset to previous commit (destructive)
+git reset --hard HEAD~1
+git push --force  # Dangerous! Only if not shared
+```
+
+## Error Prevention
+
+### Pre-commit Checks
+
+```bash
+# Check all versions match before committing
+V1=$(grep '"version"' package.json | head -1 | sed 's/.*"\([^"]*\)".*/\1/')
+V2=$(grep '"version"' .claude-plugin/marketplace.json | sed 's/.*"\([^"]*\)".*/\1/')
+V3=$(grep '"version"' plugin/.claude-plugin/plugin.json | head -1 | sed 's/.*"\([^"]*\)".*/\1/')
+
+if [ "$V1" = "$V2" ] && [ "$V2" = "$V3" ]; then
+  echo "✓ All versions match: $V1"
+else
+  echo "✗ Version mismatch!"
+  echo "  package.json: $V1"
+  echo "  marketplace.json: $V2"
+  echo "  plugin.json: $V3"
+fi
+```
+
+### Pre-push Checks
+
+```bash
+# Check tag exists
+git tag -l | grep vX.Y.Z || echo "Warning: Tag not created"
+
+# Check build succeeds
+npm run build || echo "Error: Build failed"
+
+# Check no uncommitted changes
+git status --porcelain | grep -q . && echo "Warning: Uncommitted changes"
+```
@@ -0,0 +1,218 @@
+# Common Version Bump Scenarios
+
+Real-world examples of version bumps with decision rationale.
+
+## Scenario 1: Bug Fix After Testing
+
+**User request:**
+> "Fixed the memory leak in the search function"
+
+**Analysis:**
+- What changed: Bug fix
+- Breaking changes: No
+- New features: No
+- **Decision: PATCH**
+
+**Workflow:**
+```
+Current: 4.2.8
+New: 4.2.9 (PATCH)
+
+Steps:
+1. Update all three files to 4.2.9
+2. npm run build
+3. git commit -m "Release v4.2.9: Fixed memory leak in search"
+4. git tag v4.2.9 -m "Release v4.2.9: Fixed memory leak in search"
+5. git push && git push --tags
+6. gh release create v4.2.9 --title "v4.2.9" --notes "Fixed memory leak in search function"
+```
+
+## Scenario 2: New Feature Added
+
+**User request:**
+> "Added web search MCP integration"
+
+**Analysis:**
+- What changed: New feature (MCP integration)
+- Breaking changes: No
+- Backward compatible: Yes
+- **Decision: MINOR**
+
+**Workflow:**
+```
+Current: 4.2.8
+New: 4.3.0 (MINOR - reset patch to 0)
+
+Steps:
+1. Update all three files to 4.3.0
+2. npm run build
+3. git commit -m "Release v4.3.0: Added web search MCP integration"
+4. git tag v4.3.0 -m "Release v4.3.0: Added web search MCP integration"
+5. git push && git push --tags
+6. gh release create v4.3.0 --title "v4.3.0" --generate-notes
+```
+
+## Scenario 3: Database Schema Redesign
+
+**User request:**
+> "Rewrote storage layer, old data needs migration"
+
+**Analysis:**
+- What changed: Storage layer rewrite
+- Breaking changes: Yes (requires migration)
+- Backward compatible: No
+- **Decision: MAJOR**
+
+**Workflow:**
+```
+Current: 4.2.8
+New: 5.0.0 (MAJOR - reset minor and patch to 0)
+
+Steps:
+1. Update all three files to 5.0.0
+2. npm run build
+3. git commit -m "Release v5.0.0: Storage layer redesign with migration required"
+4. git tag v5.0.0 -m "Release v5.0.0: Storage layer redesign"
+5. git push && git push --tags
+6. gh release create v5.0.0 --title "v5.0.0" --notes "⚠️ Breaking change: Storage layer redesigned. Migration required."
+```
+
+## Scenario 4: Multiple Small Bug Fixes
+
+**User request:**
+> "Fixed three bugs: observer crash, viewer pagination, and date formatting"
+
+**Analysis:**
+- What changed: Multiple bug fixes
+- Breaking changes: No
+- New features: No
+- **Decision: PATCH** (one patch covers all fixes)
+
+**Workflow:**
+```
+Current: 4.2.8
+New: 4.2.9 (PATCH)
+
+Steps:
+1. Update all three files to 4.2.9
+2. npm run build
+3. git commit -m "Release v4.2.9: Multiple bug fixes
+
+- Fixed observer crash on empty content
+- Fixed viewer pagination edge case
+- Fixed date formatting in timeline"
+4. git tag v4.2.9 -m "Release v4.2.9: Multiple bug fixes"
+5. git push && git push --tags
+6. gh release create v4.2.9 --title "v4.2.9" --generate-notes
+```
+
+## Scenario 5: Feature + Bug Fix
+
+**User request:**
+> "Added dark mode support and fixed the viewer crash bug"
+
+**Analysis:**
+- What changed: New feature + bug fix
+- Breaking changes: No
+- **Decision: MINOR** (feature trumps bug fix)
+
+**Workflow:**
+```
+Current: 5.1.0
+New: 5.2.0 (MINOR)
+
+Steps:
+1. Update all three files to 5.2.0
+2. npm run build
+3. git commit -m "Release v5.2.0: Dark mode support + bug fixes
+
+Features:
+- Added dark mode toggle to viewer UI
+
+Bug fixes:
+- Fixed viewer crash on empty database"
+4. git tag v5.2.0 -m "Release v5.2.0: Dark mode support"
+5. git push && git push --tags
+6. gh release create v5.2.0 --title "v5.2.0" --generate-notes
+```
+
+## Scenario 6: Documentation Only
+
+**User request:**
+> "Updated README with new installation instructions"
+
+**Analysis:**
+- What changed: Documentation only
+- Breaking changes: No
+- Code changes: No
+- **Decision: PATCH** (or skip version bump if no code changes)
+
+**Workflow:**
+```
+Option 1: PATCH (if you want to tag doc improvements)
+Current: 4.2.8
+New: 4.2.9
+
+Option 2: No version bump (documentation-only changes don't require versioning)
+Just commit without bumping version
+```
+
+**Recommendation:** Skip version bump for documentation-only changes unless it's a significant documentation overhaul.
+
+## Scenario 7: Configuration Change
+
+**User request:**
+> "Changed default observation count from 50 to 30"
+
+**Analysis:**
+- What changed: Default configuration
+- Breaking changes: Yes (behavior changes)
+- Users might notice different context size
+- **Decision: MINOR or MAJOR** (ask user)
+
+**Workflow:**
+```
+Ask user:
+"This changes default behavior (context size). Users will see different results.
+Is this:
+- MINOR (acceptable behavior change): 4.2.8 → 4.3.0
+- MAJOR (breaking change): 4.2.8 → 5.0.0
+
+Which should I use?"
+```
+
+## Scenario 8: Dependency Update
+
+**User request:**
+> "Updated Claude SDK from 1.2.0 to 1.3.0"
+
+**Analysis:**
+- What changed: Dependency version
+- Breaking changes: Depends on SDK changes
+- **Decision: Ask user or check SDK changelog**
+
+**Workflow:**
+```
+1. Check SDK changelog for breaking changes
+2. If SDK has breaking changes → MAJOR
+3. If SDK adds features → MINOR
+4. If SDK only fixes bugs → PATCH
+
+Typical: PATCH (unless SDK breaks compatibility)
+```
+
+## Decision Tree
+
+```
+Is there a breaking change?
+├─ Yes → MAJOR (X.0.0)
+└─ No
+   ├─ Is there a new feature?
+   │  ├─ Yes → MINOR (x.Y.0)
+   │  └─ No
+   │     ├─ Is there a bug fix?
+   │     │  ├─ Yes → PATCH (x.y.Z)
+   │     │  └─ No → Don't bump version (docs only, etc.)
+   │     └─ Configuration change? → Ask user (MINOR or MAJOR)
+   └─ Multiple changes? → Use highest level (MAJOR > MINOR > PATCH)
+```
@@ -0,0 +1,249 @@
+# Detailed Version Bump Workflow
+
+Step-by-step process for bumping versions in the claude-mem project.
+
+## Step 1: Analyze Changes
+
+First, understand what changed:
+
+```bash
+# View recent commits
+git log --oneline -5
+
+# See what changed in last commit
+git diff HEAD~1
+
+# Or see all changes since last tag
+LAST_TAG=$(git describe --tags --abbrev=0)
+git log $LAST_TAG..HEAD --oneline
+git diff $LAST_TAG..HEAD
+```
+
+## Step 2: Determine Version Type
+
+Ask yourself:
+- **Breaking changes?** → MAJOR
+- **New features?** → MINOR
+- **Bugfixes only?** → PATCH
+
+**If unclear, ASK THE USER explicitly.**
+
+### Decision Matrix
+
+| Change Type | Version Bump | Example |
+|------------|--------------|---------|
+| Bug fix | PATCH | 4.2.8 → 4.2.9 |
+| New feature (backward compatible) | MINOR | 4.2.8 → 4.3.0 |
+| Breaking change | MAJOR | 4.2.8 → 5.0.0 |
+| Multiple features | MINOR | 4.2.8 → 4.3.0 |
+| Feature + breaking change | MAJOR | 4.2.8 → 5.0.0 |
+
+## Step 3: Calculate New Version
+
+From current version in `package.json`:
+
+```bash
+grep '"version"' package.json
+```
+
+Apply semantic versioning rules:
+- **Patch:** increment Z (4.2.8 → 4.2.9)
+- **Minor:** increment Y, reset Z (4.2.8 → 4.3.0)
+- **Major:** increment X, reset Y and Z (4.2.8 → 5.0.0)
+
+## Step 4: Preview Changes
+
+**BEFORE making changes, show the user:**
+
+```
+Current version: 4.2.8
+New version: 4.2.9 (PATCH)
+Reason: Fixed database query bug
+
+Files to update:
+- package.json: "version": "4.2.9"
+- marketplace.json: "version": "4.2.9"
+- plugin.json: "version": "4.2.9"
+- Git tag: v4.2.9
+
+Proceed? (yes/no)
+```
+
+Wait for user confirmation before proceeding.
+
+## Step 5: Update Files
+
+### Update package.json
+
+File: `package.json`
+
+```json
+{
+  "name": "claude-mem",
+  "version": "4.2.9",
+  ...
+}
+```
+
+Update line 3 with new version.
+
+### Update marketplace.json
+
+File: `.claude-plugin/marketplace.json`
+
+```json
+{
+  "name": "claude-mem",
+  "version": "4.2.9",
+  ...
+}
+```
+
+Update line 13 with new version.
+
+### Update plugin.json
+
+File: `plugin/.claude-plugin/plugin.json`
+
+```json
+{
+  "name": "claude-mem",
+  "version": "4.2.9",
+  ...
+}
+```
+
+Update line 3 with new version.
+
+## Step 6: Verify Consistency
+
+```bash
+# Check all versions match
+grep -n '"version"' package.json .claude-plugin/marketplace.json plugin/.claude-plugin/plugin.json
+
+# Should show same version in all three files:
+# package.json:3:  "version": "4.2.9",
+# .claude-plugin/marketplace.json:13:  "version": "4.2.9",
+# plugin/.claude-plugin/plugin.json:3:  "version": "4.2.9",
+```
+
+All three must match exactly.
+
+## Step 7: Test
+
+```bash
+# Verify the plugin loads correctly
+npm run build
+```
+
+Build must succeed before proceeding.
+
+## Step 8: Commit and Tag
+
+```bash
+# Stage all version files
+git add package.json .claude-plugin/marketplace.json plugin/.claude-plugin/plugin.json plugin/scripts/
+
+# Commit with descriptive message
+git commit -m "Release vX.Y.Z: [Brief description]
+
+[Optional detailed description]
+
+🤖 Generated with [Claude Code](https://claude.com/claude-code)
+
+Co-Authored-By: Claude <noreply@anthropic.com>"
+
+# Create annotated git tag
+git tag vX.Y.Z -m "Release vX.Y.Z: [Brief description]"
+
+# Push commit and tags
+git push && git push --tags
+```
+
+Replace `X.Y.Z` with actual version (e.g., `4.2.9`).
+
+## Step 9: Create GitHub Release
+
+```bash
+# Create GitHub release from the tag
+gh release create vX.Y.Z --title "vX.Y.Z" --notes "[Brief release notes]"
+
+# Or generate notes automatically from commits
+gh release create vX.Y.Z --title "vX.Y.Z" --generate-notes
+```
+
+**IMPORTANT:** Always create the GitHub release immediately after pushing the tag. This makes the release discoverable to users and triggers any automated workflows.
+
+## Step 10: Generate CHANGELOG
+
+After creating the GitHub release, regenerate CHANGELOG.md from all releases:
+
+```bash
+# Generate CHANGELOG.md from all GitHub releases
+npm run changelog:generate
+
+# Review the generated changelog
+git diff CHANGELOG.md
+
+# Commit and push the updated changelog
+git add CHANGELOG.md
+git commit -m "Update CHANGELOG.md for vX.Y.Z release"
+git push
+```
+
+**Why this step:**
+- CHANGELOG.md is auto-generated from GitHub releases
+- Keeps the changelog in sync with release notes
+- No manual editing required
+- Single source of truth: GitHub releases
+
+## Step 11: Discord Notification
+
+Post release announcement to the Discord updates channel:
+
+```bash
+# Send Discord notification with release details
+npm run discord:notify vX.Y.Z
+```
+
+This fetches the release notes from GitHub and posts a formatted embed to the Discord updates channel configured in `.env`.
+
+## Verification
+
+After completing all steps, verify:
+
+```bash
+# Check git tag created
+git tag -l | grep vX.Y.Z
+
+# Check remote has tag
+git ls-remote --tags origin | grep vX.Y.Z
+
+# Check GitHub release exists
+gh release view vX.Y.Z
+
+# Verify versions match
+grep '"version"' package.json .claude-plugin/marketplace.json plugin/.claude-plugin/plugin.json
+```
+
+All checks should pass.
+
+## Rollback (If Needed)
+
+If you made a mistake:
+
+```bash
+# Delete local tag
+git tag -d vX.Y.Z
+
+# Delete remote tag (if already pushed)
+git push origin :refs/tags/vX.Y.Z
+
+# Delete GitHub release (if created)
+gh release delete vX.Y.Z
+
+# Revert commits if needed
+git revert HEAD
+```
+
+Then restart the workflow with correct version.
@@ -7,12 +7,6 @@ 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:
@@ -7,12 +7,6 @@ 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 [...]

@@ -1,7 +0,0 @@
-<claude-mem-context>
-# claude-mem: Cross-Session Memory
-
-*No context yet. Complete your first session and context will appear here.*
-
-Use claude-mem's MCP search tools for manual memory queries.
-</claude-mem-context>
@@ -27,7 +27,7 @@ jobs:

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

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

@@ -26,7 +26,7 @@ jobs:
    steps:
      - name: Get issue details and create discussion
        id: discussion
-        uses: actions/github-script@v8
+        uses: actions/github-script@v7
        with:
          script: |
            // Get issue details
@@ -87,7 +87,7 @@ jobs:
            }

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

      - name: Close and lock issue
-        uses: actions/github-script@v8
+        uses: actions/github-script@v7
        with:
          script: |
            const issueNumber = ${{ steps.discussion.outputs.issue_number }};
@@ -1,29 +0,0 @@
-name: Deploy Install Scripts
-
-on:
-  push:
-    branches: [main]
-    paths:
-      - 'openclaw/install.sh'
-      - 'install/**'
-  workflow_dispatch:
-
-jobs:
-  deploy:
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@v4
-
-      - name: Copy install scripts to deploy directory
-        run: |
-          mkdir -p install/public
-          cp openclaw/install.sh install/public/openclaw.sh
-
-      - name: Deploy to Vercel
-        uses: amondnet/vercel-action@v25
-        with:
-          vercel-token: ${{ secrets.VERCEL_TOKEN }}
-          vercel-org-id: ${{ secrets.VERCEL_ORG_ID }}
-          vercel-project-id: ${{ secrets.VERCEL_PROJECT_ID }}
-          vercel-args: '--prod'
-          working-directory: ./install
@@ -1,21 +0,0 @@
-name: Publish to npm
-
-on:
-  push:
-    tags:
-      - 'v*'
-
-jobs:
-  publish:
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@v4
-      - uses: actions/setup-node@v4
-        with:
-          node-version: '20'
-          registry-url: 'https://registry.npmjs.org'
-      - run: npm install --ignore-scripts
-      - run: npm run build
-      - run: npm publish
-        env:
-          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
@@ -14,11 +14,11 @@ jobs:

    steps:
      - name: Checkout repository
-        uses: actions/checkout@v6
+        uses: actions/checkout@v4

      - name: Run AI inference
        id: inference
-        uses: actions/ai-inference@v2
+        uses: actions/ai-inference@v1
        with:
          prompt: |
            Summarize the following GitHub issue in one paragraph:
@@ -1,7 +1,6 @@
 datasets/
 node_modules/
 dist/
-**/_tree-sitter/
 *.log
 .DS_Store
 .env
@@ -10,31 +9,14 @@ dist/
 *.temp
 .install-version
 .claude/settings.local.json
-.claude/agents/
-.claude/skills/
-.claude/plans/
-.claude/worktrees/
 plugin/data/
 plugin/data.backup/
 package-lock.json
-bun.lock
 private/
-Auto Run Docs/
+datasets/

 # Generated UI files (built from viewer-template.html)
 src/ui/viewer.html

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

+## What This Project Is
+
 Claude-mem is a Claude Code plugin providing persistent memory across sessions. It captures tool usage, compresses observations using the Claude Agent SDK, and injects relevant context into future sessions.

 ## Architecture
@@ -10,20 +14,19 @@ Claude-mem is a Claude Code plugin providing persistent memory across sessions.

 **Worker Service** (`src/services/worker-service.ts`) - Express API on port 37777, Bun-managed, handles AI processing asynchronously

-**Database** (`src/services/sqlite/`) - SQLite3 at `~/.claude-mem/claude-mem.db`
+**Database** (`src/services/sqlite/`) - SQLite3 at `~/.claude-mem/claude-mem.db` 

 **Search Skill** (`plugin/skills/mem-search/SKILL.md`) - HTTP API for searching past work, auto-invoked when users ask about history

-**Planning Skill** (`plugin/skills/make-plan/SKILL.md`) - Orchestrator instructions for creating phased implementation plans with documentation discovery
-
-**Execution Skill** (`plugin/skills/do/SKILL.md`) - Orchestrator instructions for executing phased plans using subagents
-
 **Chroma** (`src/services/sync/ChromaSync.ts`) - Vector embeddings for semantic search

 **Viewer UI** (`src/ui/viewer/`) - React interface at http://localhost:37777, built to `plugin/ui/viewer.html`

 ## Privacy Tags
+
+**Dual-Tag System** for meta-observation control:
 - `<private>content</private>` - User-level privacy control (manual, prevents storage)
+- `<claude-mem-context>content</claude-mem-context>` - System-level tag (auto-injected observations, prevents recursive storage)

 **Implementation**: Tag stripping happens at hook layer (edge processing) before data reaches worker/database. See `src/utils/tag-stripping.ts` for shared utilities.

@@ -45,18 +48,6 @@ Settings are managed in `~/.claude-mem/settings.json`. The file is auto-created
 - **Database**: `~/.claude-mem/claude-mem.db`
 - **Chroma**: `~/.claude-mem/chroma/`

-## Exit Code Strategy
-
-Claude-mem hooks use specific exit codes per Claude Code's hook contract:
-
- **Exit 0**: Success or graceful shutdown (Windows Terminal closes tabs)
- **Exit 1**: Non-blocking error (stderr shown to user, continues)
- **Exit 2**: Blocking error (stderr fed to Claude for processing)
-
-**Philosophy**: Worker/hook errors exit with code 0 to prevent Windows Terminal tab accumulation. The wrapper/plugin layer handles restart logic. ERROR-level logging is maintained for diagnostics.
-
-See `private/context/claude-code/exit-codes.md` for full hook behavior matrix.
-
 ## Requirements

 - **Bun** (all platforms - auto-installed if missing)
@@ -89,6 +80,7 @@ Claude-mem is designed with a clean separation between open-source core function

 This architecture preserves the open-source nature of the project while enabling sustainable development through optional paid features.

-## Important
+# Important

 No need to edit the changelog ever, it's generated automatically.
+No need to run tests, they are useless and are always deleted.
@@ -1,3 +1,5 @@
+
+
 <h1 align="center">
  <br>
  <a href="https://github.com/thedotmack/claude-mem">
@@ -12,14 +14,12 @@

 <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.md">🇵🇹 Português</a> •
  <a href="docs/i18n/README.pt-br.md">🇧🇷 Português</a> •
  <a href="docs/i18n/README.ko.md">🇰🇷 한국어</a> •
  <a href="docs/i18n/README.es.md">🇪🇸 Español</a> •
  <a href="docs/i18n/README.de.md">🇩🇪 Deutsch</a> •
-  <a href="docs/i18n/README.fr.md">🇫🇷 Français</a> •
+  <a href="docs/i18n/README.fr.md">🇫🇷 Français</a>
  <a href="docs/i18n/README.he.md">🇮🇱 עברית</a> •
  <a href="docs/i18n/README.ar.md">🇸🇦 العربية</a> •
  <a href="docs/i18n/README.ru.md">🇷🇺 Русский</a> •
@@ -29,12 +29,10 @@
  <a href="docs/i18n/README.tr.md">🇹🇷 Türkçe</a> •
  <a href="docs/i18n/README.uk.md">🇺🇦 Українська</a> •
  <a href="docs/i18n/README.vi.md">🇻🇳 Tiếng Việt</a> •
-  <a href="docs/i18n/README.tl.md">🇵🇭 Tagalog</a> •
  <a href="docs/i18n/README.id.md">🇮🇩 Indonesia</a> •
  <a href="docs/i18n/README.th.md">🇹🇭 ไทย</a> •
  <a href="docs/i18n/README.hi.md">🇮🇳 हिन्दी</a> •
  <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> •
@@ -74,40 +72,13 @@

 <br>

-<table align="center">
-  <tr>
-    <td align="center">
-      <a href="https://github.com/thedotmack/claude-mem">
-        <picture>
-          <img
-            src="https://raw.githubusercontent.com/thedotmack/claude-mem/main/docs/public/cm-preview.gif"
-            alt="Claude-Mem Preview"
-            width="500"
-          >
-        </picture>
-      </a>
-    </td>
-    <td align="center">
-      <a href="https://www.star-history.com/#thedotmack/claude-mem&Date">
-        <picture>
-          <source
-            media="(prefers-color-scheme: dark)"
-            srcset="https://api.star-history.com/image?repos=thedotmack/claude-mem&type=date&theme=dark&legend=top-left"
-          />
-          <source
-            media="(prefers-color-scheme: light)"
-            srcset="https://api.star-history.com/image?repos=thedotmack/claude-mem&type=date&legend=top-left"
-          />
-          <img
-            alt="Star History Chart"
-            src="https://api.star-history.com/image?repos=thedotmack/claude-mem&type=date&legend=top-left"
-            width="500"
-          />
-        </picture>
-      </a>
-    </td>
-  </tr>
-</table>
+<p align="center">
+  <a href="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="#quick-start">Quick Start</a> •
@@ -127,39 +98,15 @@

 ## Quick Start

-Install with a single command:
+Start a new Claude Code session in the terminal and enter the following commands:

-```bash
-npx claude-mem install
+```
+> /plugin marketplace add thedotmack/claude-mem
+
+> /plugin install claude-mem
 ```

-Or install for Gemini CLI (auto-detects `~/.gemini`):
-
-```bash
-npx claude-mem install --ide gemini-cli
-```
-
-Or install from the plugin marketplace inside Claude Code:
-
-```bash
-/plugin marketplace add thedotmack/claude-mem
-
-/plugin install claude-mem
-```
-
-Restart Claude Code or Gemini CLI. Context from previous sessions will automatically appear in new sessions.
-
-> **Note:** Claude-Mem is also published on npm, but `npm install -g claude-mem` installs the **SDK/library only** — it does not register the plugin hooks or set up the worker service. Always install via `npx claude-mem install` or the `/plugin` commands above.
-
-### 🦞 OpenClaw Gateway
-
-Install claude-mem as a persistent memory plugin on [OpenClaw](https://openclaw.ai) gateways with a single command:
-
-```bash
-curl -fsSL https://install.cmem.ai/openclaw.sh | bash
-```
-
-The installer handles dependencies, plugin setup, AI provider configuration, worker startup, and optional real-time observation feeds to Telegram, Discord, Slack, and more. See the [OpenClaw Integration Guide](https://docs.claude-mem.ai/openclaw-integration) for details.
+Restart Claude Code. Context from previous sessions will automatically appear in new sessions.

 **Key Features:**

@@ -178,12 +125,11 @@ The installer handles dependencies, plugin setup, AI provider configuration, wor

 ## Documentation

-📚 **[View Full Documentation](https://docs.claude-mem.ai/)** - Browse on official website
+📚 **[View Full Documentation](docs/)** - Browse markdown docs on GitHub

 ### Getting Started

 - **[Installation Guide](https://docs.claude-mem.ai/installation)** - Quick start & advanced installation
- **[Gemini CLI Setup](https://docs.claude-mem.ai/gemini-cli/setup)** - Dedicated guide for Google's Gemini CLI integration
 - **[Usage Guide](https://docs.claude-mem.ai/usage/getting-started)** - How Claude-Mem works automatically
 - **[Search Tools](https://docs.claude-mem.ai/usage/search-tools)** - Query your project history with natural language
 - **[Beta Features](https://docs.claude-mem.ai/beta-features)** - Try experimental features like Endless Mode
@@ -226,39 +172,35 @@ See [Architecture Overview](https://docs.claude-mem.ai/architecture/overview) fo

 ---

-## MCP Search Tools
+## mem-search Skill

-Claude-Mem provides intelligent memory search through **4 MCP tools** following a token-efficient **3-layer workflow pattern**:
-
-**The 3-Layer Workflow:**
-
-1. **`search`** - Get compact index with IDs (~50-100 tokens/result)
-2. **`timeline`** - Get chronological context around interesting results
-3. **`get_observations`** - Fetch full details ONLY for filtered IDs (~500-1,000 tokens/result)
+Claude-Mem provides intelligent search through the mem-search skill that auto-invokes when you ask about past work:

 **How It Works:**
- Claude uses MCP tools to search your memory
- 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
- **~10x token savings** by filtering before fetching details
+- Just ask naturally: *"What did we do last session?"* or *"Did we fix this bug before?"*
+- Claude automatically invokes the mem-search skill to find relevant context

-**Available MCP Tools:**
+**Available Search Operations:**

-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)
+1. **Search Observations** - Full-text search across observations
+2. **Search Sessions** - Full-text search across session summaries
+3. **Search Prompts** - Search raw user requests
+4. **By Concept** - Find by concept tags (discovery, problem-solution, pattern, etc.)
+5. **By File** - Find observations referencing specific files
+6. **By Type** - Find by type (decision, bugfix, feature, refactor, discovery, change)
+7. **Recent Context** - Get recent session context for a project
+8. **Timeline** - Get unified timeline of context around a specific point in time
+9. **Timeline by Query** - Search for observations and get timeline context around best match
+10. **API Help** - Get search API documentation

-**Example Usage:**
+**Example Natural Language Queries:**

-```typescript
-// Step 1: Search for index
-search(query="authentication bug", type="bugfix", limit=10)
-
-// Step 2: Review index, identify relevant IDs (e.g., #123, #456)
-
-// Step 3: Fetch full details
-get_observations(ids=[123, 456])
+```
+"What bugs did we fix last session?"
+"How did we implement authentication?"
+"What changes were made to worker-service.ts?"
+"Show me recent work on this project"
+"What was happening when we added the viewer UI?"
 ```

 See [Search Tools Guide](https://docs.claude-mem.ai/usage/search-tools) for detailed examples.
@@ -281,17 +223,6 @@ 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
@@ -363,16 +294,8 @@ See the [LICENSE](LICENSE) file for full details.
 - **Documentation**: [docs/](docs/)
 - **Issues**: [GitHub Issues](https://github.com/thedotmack/claude-mem/issues)
 - **Repository**: [github.com/thedotmack/claude-mem](https://github.com/thedotmack/claude-mem)
- **Official X Account**: [@Claude_Memory](https://x.com/Claude_Memory)
- **Official Discord**: [Join Discord](https://discord.com/invite/J4wttp9vDu)
 - **Author**: Alex Newman ([@thedotmack](https://github.com/thedotmack))

 ---

 **Built with Claude Agent SDK** | **Powered by Claude Code** | **Made with TypeScript**
-
---
-
-### What About $CMEM?
-
-$CMEM is a solana token created by a 3rd party without Claude-Mem's prior consent, but officially embraced by the creator of Claude-Mem (Alex Newman, @thedotmack). The token acts as a community catalyst for growth and a vehicle for bringing real-time agent data to the developers and knowledge workers that need it most. $CMEM: 2TsmuYUrsctE57VLckZBYEEzdokUF8j8e1GavekWBAGS
@@ -1,7 +0,0 @@
-<claude-mem-context>
-# claude-mem: Cross-Session Memory
-
-*No context yet. Complete your first session and context will appear here.*
-
-Use claude-mem's MCP search tools for manual memory queries.
-</claude-mem-context>
@@ -1,6 +0,0 @@
-{
-    "scripts": {
-        "setup": "cp ../settings.local.json .claude/settings.local.json && npm install",
-        "run": "npm run build-and-sync"
-    }
-}
@@ -1,3 +0,0 @@
-# Ignore backup files created by sed
-*.bak
-
@@ -1,173 +0,0 @@
-# Context Injection in Cursor Hooks
-
-## The Solution: Auto-Updated Rules File
-
-Context is automatically injected via Cursor's **Rules** system:
-
-1. **Install**: `claude-mem cursor install` creates initial context file
-2. **Stop hook**: `session-summary.sh` updates context after each session ends
-3. **Cursor**: Automatically includes `.cursor/rules/claude-mem-context.mdc` in all chats
-
-**Result**: Context appears at the start of every conversation, just like Claude Code!
-
-## How It Works
-
-### Installation Creates Initial Context
-
-```bash
-claude-mem cursor install
-```
-
-This:
-1. Copies hook scripts to `.cursor/hooks/`
-2. Creates `hooks.json` configuration
-3. Fetches existing context from claude-mem and writes to `.cursor/rules/claude-mem-context.mdc`
-
-### Context Updates at Three Points
-
-Context is refreshed **three times** per session for maximum freshness:
-
-1. **Before prompt submission** (`context-inject.sh`): Ensures you start with the latest context from previous sessions
-2. **After summary completes** (worker auto-update): Immediately after the summary is saved, worker updates the context file
-3. **After session ends** (`session-summary.sh`): Fallback update in case worker update was missed
-
-### Before Prompt Hook Updates Context
-
-When you submit a prompt, `context-inject.sh`:
-
-```bash
-# 1. Ensure worker is running
-ensure_worker_running "$worker_port"
-
-# 2. Fetch fresh context
-context=$(curl -s ".../api/context/inject?project=...")
-
-# 3. Write to rules file (used immediately by Cursor)
-cat > .cursor/rules/claude-mem-context.mdc << EOF
---
-alwaysApply: true
---
-# Memory Context
-${context}
-EOF
-```
-
-### Stop Hook Updates Context
-
-After each session ends, `session-summary.sh`:
-
-```bash
-# 1. Generate session summary
-curl -X POST .../api/sessions/summarize
-
-# 2. Fetch fresh context (includes new observations)
-context=$(curl -s ".../api/context/inject?project=...")
-
-# 3. Write to rules file for next session
-cat > .cursor/rules/claude-mem-context.mdc << EOF
---
-alwaysApply: true
---
-# Memory Context
-${context}
-EOF
-```
-
-### The Rules File
-
-Located at: `.cursor/rules/claude-mem-context.mdc`
-
-```markdown
---
-alwaysApply: true
-description: "Claude-mem context from past sessions (auto-updated)"
---
-
-# Memory Context from Past Sessions
-
-[Your context from claude-mem appears here]
-
---
-*Updated after last session.*
-```
-
-### Update Flow
-
-Context updates at **three points**:
-
-**Before each prompt:**
-1. User submits a prompt
-2. `beforeSubmitPrompt` hook runs `context-inject.sh`
-3. Context file refreshed with latest observations from previous sessions
-4. Cursor reads the updated rules file
-
-**After summary completes (worker auto-update):**
-1. Summary is saved to database
-2. Worker checks if project is registered for Cursor
-3. If yes, immediately writes updated context file with new observations
-4. No hook involved - happens in the worker process
-
-**After session ends (fallback):**
-1. Agent completes (loop ends)
-2. `stop` hook runs `session-summary.sh`
-3. Context file updated (ensures nothing was missed)
-4. Ready for next session
-
-## Project Registry
-
-When you run `claude-mem cursor install`, the project is registered in `~/.claude-mem/cursor-projects.json`. This allows the worker to automatically update your context file whenever a new summary is generated - even if it happens from Claude Code or another IDE working on the same project.
-
-To see registered projects:
-```bash
-cat ~/.claude-mem/cursor-projects.json
-```
-
-## Comparison with Claude Code
-
-| Feature | Claude Code | Cursor |
-|---------|-------------|--------|
-| Context injection | ✅ `additionalContext` in hook output | ✅ Auto-updated rules file |
-| Injection timing | Immediate (same prompt) | Before prompt + after summary + after session |
-| Persistence | Session only | File-based (persists across restarts) |
-| Initial setup | Automatic | `claude-mem cursor install` creates initial context |
-| MCP tool access | ✅ Full support | ✅ Full support |
-| Web viewer | ✅ Available | ✅ Available |
-
-## First Session Behavior
-
-When you run `claude-mem cursor install`:
- If worker is running with existing memory → initial context is generated
- If no existing memory → placeholder file created
-
-Context is then automatically refreshed:
- Before each prompt (ensures latest observations are included)
- After each session ends (captures new observations from the session)
-
-## Additional Access Methods
-
-### 1. MCP Tools
-
-Configure claude-mem's MCP server in Cursor for search tools:
- `search(query, project, limit)`
- `timeline(anchor, depth_before, depth_after)`
- `get_observations(ids)`
-
-### 2. Web Viewer
-
-Access context manually at `http://localhost:37777`
-
-### 3. Manual Request
-
-Ask the agent: "Check claude-mem for any previous work on authentication"
-
-## File Location
-
-The context file is created at:
-```
-<workspace>/.cursor/rules/claude-mem-context.mdc
-```
-
-This is version-controlled by default. Add to `.gitignore` if you don't want to commit it:
-```
-.cursor/rules/claude-mem-context.mdc
-```
@@ -1,251 +0,0 @@
-# Claude-Mem ↔ Cursor Integration Architecture
-
-## Overview
-
-This integration connects claude-mem's persistent memory system to Cursor's hook system, enabling:
- Automatic capture of agent actions (MCP tools, shell commands, file edits)
- Context retrieval from past sessions
- Session summarization for future reference
-
-## Architecture
-
-```
-┌─────────────┐
-│   Cursor    │
-│   Agent     │
-└──────┬──────┘
-       │
-       │ Events (MCP, Shell, File Edits, Prompts)
-       │
-       ▼
-┌─────────────────────────────────────┐
-│      Cursor Hooks System             │
-│  ┌────────────────────────────────┐ │
-│  │ beforeSubmitPrompt             │ │
-│  │ afterMCPExecution              │ │
-│  │ afterShellExecution            │ │
-│  │ afterFileEdit                  │ │
-│  │ stop                           │ │
-│  └────────────────────────────────┘ │
-└──────┬──────────────────────────────┘
-       │
-       │ HTTP Requests
-       │
-       ▼
-┌─────────────────────────────────────┐
-│   Hook Scripts (Bash)               │
-│  ┌────────────────────────────────┐ │
-│  │ session-init.sh               │ │
-│  │ context-inject.sh             │ │
-│  │ save-observation.sh          │ │
-│  │ save-file-edit.sh             │ │
-│  │ session-summary.sh            │ │
-│  └────────────────────────────────┘ │
-└──────┬──────────────────────────────┘
-       │
-       │ HTTP API Calls
-       │
-       ▼
-┌─────────────────────────────────────┐
-│   Claude-Mem Worker Service         │
-│   (Port 37777)                      │
-│  ┌────────────────────────────────┐ │
-│  │ /api/sessions/init            │ │
-│  │ /api/sessions/observations    │ │
-│  │ /api/sessions/summarize       │ │
-│  │ /api/context/inject          │ │
-│  └────────────────────────────────┘ │
-└──────┬──────────────────────────────┘
-       │
-       │ Database Operations
-       │
-       ▼
-┌─────────────────────────────────────┐
-│   SQLite Database                    │
-│   + Chroma Vector DB                 │
-└─────────────────────────────────────┘
-```
-
-## Event Flow
-
-### 1. Prompt Submission Flow
-
-```
-User submits prompt
-    ↓
-beforeSubmitPrompt hook fires
-    ↓
-session-init.sh
-    ├─ Extract conversation_id, project name
-    ├─ POST /api/sessions/init
-    └─ Initialize session in claude-mem
-    ↓
-context-inject.sh
-    ├─ GET /api/context/inject?project=...
-    └─ Fetch relevant context (for future use)
-    ↓
-Prompt proceeds to agent
-```
-
-### 2. Tool Execution Flow
-
-```
-Agent executes MCP tool or shell command
-    ↓
-afterMCPExecution / afterShellExecution hook fires
-    ↓
-save-observation.sh
-    ├─ Extract tool_name, tool_input, tool_response
-    ├─ Map to claude-mem observation format
-    ├─ POST /api/sessions/observations
-    └─ Store observation in database
-```
-
-### 3. File Edit Flow
-
-```
-Agent edits file
-    ↓
-afterFileEdit hook fires
-    ↓
-save-file-edit.sh
-    ├─ Extract file_path, edits
-    ├─ Create "write_file" observation
-    ├─ POST /api/sessions/observations
-    └─ Store file edit observation
-```
-
-### 4. Session End Flow
-
-```
-Agent loop ends
-    ↓
-stop hook fires
-    ↓
-session-summary.sh
-    ├─ POST /api/sessions/summarize
-    └─ Generate session summary for future retrieval
-```
-
-## Data Mapping
-
-### Session ID Mapping
-
-| Cursor Field | Claude-Mem Field | Notes |
-|-------------|------------------|-------|
-| `conversation_id` | `contentSessionId` | Stable across turns, used as primary session identifier |
-| `generation_id` | (fallback) | Used if conversation_id unavailable |
-
-### Tool Mapping
-
-| Cursor Event | Claude-Mem Tool Name | Input Format |
-|-------------|---------------------|--------------|
-| `afterMCPExecution` | `tool_name` from event | `tool_input` as JSON |
-| `afterShellExecution` | `"Bash"` | `{command: "..."}` |
-| `afterFileEdit` | `"write_file"` | `{file_path: "...", edits: [...]}` |
-
-### Project Mapping
-
-| Source | Target | Notes |
-|--------|--------|-------|
-| `workspace_roots[0]` | Project name | Basename of workspace root directory |
-
-## API Endpoints Used
-
-### Session Management
- `POST /api/sessions/init` - Initialize new session
- `POST /api/sessions/summarize` - Generate session summary
-
-### Observation Storage
- `POST /api/sessions/observations` - Store tool usage observation
-
-### Context Retrieval
- `GET /api/context/inject?project=...` - Get relevant context for injection
-
-### Health Checks
- `GET /api/readiness` - Check if worker is ready
-
-## Configuration
-
-### Worker Settings
-Located in `~/.claude-mem/settings.json`:
- `CLAUDE_MEM_WORKER_PORT` (default: 37777)
- `CLAUDE_MEM_WORKER_HOST` (default: 127.0.0.1)
-
-### Hook Settings
-Located in `hooks.json`:
- Hook event names
- Script paths (relative or absolute)
-
-## Error Handling
-
-### Worker Unavailable
- Hooks poll `/api/readiness` with 30 retries (6 seconds)
- If worker unavailable, hooks fail gracefully (exit 0)
- Observations are fire-and-forget (curl errors ignored)
-
-### Missing Data
- Empty `conversation_id` → use `generation_id`
- Empty `workspace_root` → use `pwd`
- Missing tool data → skip observation
-
-### Network Errors
- All HTTP requests use `curl -s` (silent)
- Errors redirected to `/dev/null`
- Hooks always exit 0 to avoid blocking Cursor
-
-## Limitations
-
-1. **Context Injection**: Cursor's `beforeSubmitPrompt` doesn't support prompt modification. Context must be retrieved via:
-   - MCP tools (claude-mem provides search tools)
-   - Manual retrieval from web viewer
-   - Future: Agent SDK integration
-
-2. **Transcript Access**: Cursor hooks don't provide transcript paths, limiting summary quality compared to Claude Code integration.
-
-3. **Session Model**: Uses `conversation_id` which may not perfectly match Claude Code's session model.
-
-4. **Tab Hooks**: Currently only supports Agent hooks. Tab (inline completion) hooks could be added separately.
-
-## Future Enhancements
-
- [ ] Enhanced context injection via MCP tools
- [ ] Support for `beforeTabFileRead` and `afterTabFileEdit` hooks
- [ ] Better error reporting and logging
- [ ] Integration with Cursor's agent SDK
- [ ] Support for blocking/approval workflows
- [ ] Real-time context injection via agent messages
-
-## Testing
-
-### Manual Testing
-
-1. **Test session initialization**:
-   ```bash
-   echo '{"conversation_id":"test-123","workspace_roots":["/tmp/test"],"prompt":"test"}' | \
-     ~/.cursor/hooks/session-init.sh
-   ```
-
-2. **Test observation capture**:
-   ```bash
-   echo '{"conversation_id":"test-123","hook_event_name":"afterMCPExecution","tool_name":"test","tool_input":{},"result_json":{}}' | \
-     ~/.cursor/hooks/save-observation.sh
-   ```
-
-3. **Test context retrieval**:
-   ```bash
-   curl "http://127.0.0.1:37777/api/context/inject?project=test"
-   ```
-
-### Integration Testing
-
-1. Enable hooks in Cursor
-2. Submit a prompt
-3. Execute some tools
-4. Check web viewer: `http://localhost:37777`
-5. Verify observations appear in database
-
-## Troubleshooting
-
-See [README.md](README.md#troubleshooting) for detailed troubleshooting steps.
-
@@ -1,168 +0,0 @@
-# Feature Parity: Claude-Mem Hooks vs Cursor Hooks
-
-This document compares claude-mem's Claude Code hooks with the Cursor hooks implementation to ensure feature parity.
-
-## Hook Mapping
-
-| Claude Code Hook | Cursor Hook | Status | Notes |
-|-----------------|-------------|--------|-------|
-| `SessionStart` → `context-hook.js` | `beforeSubmitPrompt` → `context-inject.sh` | ✅ Partial | Context fetched but not injectable in Cursor |
-| `SessionStart` → `user-message-hook.js` | (Optional) `user-message.sh` | ⚠️ Optional | No SessionStart equivalent; can run on beforeSubmitPrompt |
-| `UserPromptSubmit` → `new-hook.js` | `beforeSubmitPrompt` → `session-init.sh` | ✅ Complete | Session init, privacy checks, slash stripping |
-| `PostToolUse` → `save-hook.js` | `afterMCPExecution` + `afterShellExecution` → `save-observation.sh` | ✅ Complete | Tool observation capture |
-| `PostToolUse` → (file edits) | `afterFileEdit` → `save-file-edit.sh` | ✅ Complete | File edit observation capture |
-| `Stop` → `summary-hook.js` | `stop` → `session-summary.sh` | ⚠️ Partial | Summary generation (no transcript access) |
-
-## Feature Comparison
-
-### 1. Session Initialization (`new-hook.js` ↔ `session-init.sh`)
-
-| Feature | Claude Code | Cursor | Status |
-|---------|-------------|--------|--------|
-| Worker health check | ✅ 75 retries (15s) | ✅ 75 retries (15s) | ✅ Match |
-| Session init API call | ✅ `/api/sessions/init` | ✅ `/api/sessions/init` | ✅ Match |
-| Privacy check handling | ✅ Checks `skipped` + `reason` | ✅ Checks `skipped` + `reason` | ✅ Match |
-| Slash stripping | ✅ Strips leading `/` | ✅ Strips leading `/` | ✅ Match |
-| SDK agent init | ✅ `/sessions/{id}/init` | ❌ Not needed | ✅ N/A (Cursor-specific) |
-
-**Status**: ✅ Complete parity (SDK agent init not applicable to Cursor)
-
-### 2. Context Injection (`context-hook.js` ↔ `context-inject.sh`)
-
-| Feature | Claude Code | Cursor | Status |
-|---------|-------------|--------|--------|
-| Worker health check | ✅ 75 retries | ✅ 75 retries | ✅ Match |
-| Context fetch | ✅ `/api/context/inject` | ✅ `/api/context/inject` | ✅ Match |
-| Output format | ✅ JSON with `hookSpecificOutput` | ✅ Write to `.cursor/rules/` file | ✅ Alternative |
-| Project name extraction | ✅ `getProjectName(cwd)` | ✅ `basename(workspace_root)` | ✅ Match |
-| Auto-refresh | ✅ Each session start | ✅ Each prompt submission | ✅ Enhanced |
-
-**Status**: ✅ Complete parity via auto-updated rules file
-
-**How it works**:
- Hook writes context to `.cursor/rules/claude-mem-context.mdc`
- File has `alwaysApply: true` frontmatter
- Cursor auto-includes this rule in all chat sessions
- Context refreshes on every prompt submission
-
-### 3. User Message Display (`user-message-hook.js` ↔ `user-message.sh`)
-
-| Feature | Claude Code | Cursor | Status |
-|---------|-------------|--------|--------|
-| Context fetch with colors | ✅ `/api/context/inject?colors=true` | ✅ `/api/context/inject?colors=true` | ✅ Match |
-| Output channel | ✅ stderr | ✅ stderr | ✅ Match |
-| Display format | ✅ Formatted with emojis | ✅ Formatted with emojis | ✅ Match |
-| Hook trigger | ✅ SessionStart | ⚠️ Optional (no SessionStart) | ⚠️ Cursor limitation |
-
-**Status**: ⚠️ Optional (no SessionStart equivalent in Cursor)
-
-**Note**: Can be added to `beforeSubmitPrompt` if desired, but may be verbose.
-
-### 4. Observation Capture (`save-hook.js` ↔ `save-observation.sh`)
-
-| Feature | Claude Code | Cursor | Status |
-|---------|-------------|--------|--------|
-| Worker health check | ✅ 75 retries | ✅ 75 retries | ✅ Match |
-| Tool name extraction | ✅ From `tool_name` | ✅ From `tool_name` or "Bash" | ✅ Match |
-| Tool input capture | ✅ Full JSON | ✅ Full JSON | ✅ Match |
-| Tool response capture | ✅ Full JSON | ✅ Full JSON or output | ✅ Match |
-| Privacy tag stripping | ✅ Worker handles | ✅ Worker handles | ✅ Match |
-| Error handling | ✅ Fire-and-forget | ✅ Fire-and-forget | ✅ Match |
-| Shell command mapping | ✅ N/A (separate hook) | ✅ Maps to "Bash" tool | ✅ Enhanced |
-
-**Status**: ✅ Complete parity (enhanced with shell command support)
-
-### 5. File Edit Capture (N/A ↔ `save-file-edit.sh`)
-
-| Feature | Claude Code | Cursor | Status |
-|---------|-------------|--------|--------|
-| File path extraction | N/A | ✅ From `file_path` | ✅ New |
-| Edit details | N/A | ✅ From `edits` array | ✅ New |
-| Tool name | N/A | ✅ "write_file" | ✅ New |
-| Edit summary | N/A | ✅ Generated from edits | ✅ New |
-
-**Status**: ✅ New feature (Cursor-specific, not in Claude Code)
-
-### 6. Session Summary (`summary-hook.js` ↔ `session-summary.sh`)
-
-| Feature | Claude Code | Cursor | Status |
-|---------|-------------|--------|--------|
-| Worker health check | ✅ 75 retries | ✅ 75 retries | ✅ Match |
-| Transcript parsing | ✅ Extracts last messages | ❌ No transcript access | ⚠️ Cursor limitation |
-| Summary API call | ✅ `/api/sessions/summarize` | ✅ `/api/sessions/summarize` | ✅ Match |
-| Last message extraction | ✅ From transcript | ❌ Empty strings | ⚠️ Cursor limitation |
-| Error handling | ✅ Fire-and-forget | ✅ Fire-and-forget | ✅ Match |
-
-**Status**: ⚠️ Partial parity (no transcript access in Cursor)
-
-**Note**: Summary generation still works but may be less accurate without last messages. Worker generates summary from observations stored during session.
-
-## Implementation Details
-
-### Worker Health Checks
- **Claude Code**: 75 retries × 200ms = 15 seconds
- **Cursor**: 75 retries × 200ms = 15 seconds
- **Status**: ✅ Match
-
-### Error Handling
- **Claude Code**: Fire-and-forget with logging
- **Cursor**: Fire-and-forget with graceful exit (exit 0)
- **Status**: ✅ Match (adapted for Cursor's hook system)
-
-### Privacy Handling
- **Claude Code**: Worker performs privacy checks, hooks respect `skipped` flag
- **Cursor**: Worker performs privacy checks, hooks respect `skipped` flag
- **Status**: ✅ Match
-
-### Tag Stripping
- **Claude Code**: Worker handles `<private>` and `<claude-mem-context>` tags
- **Cursor**: Worker handles tags (hooks don't need to strip)
- **Status**: ✅ Match
-
-## Missing Features (Cursor Limitations)
-
-1. ~~**Direct Context Injection**~~: **SOLVED** via auto-updated rules file
-   - Hook writes context to `.cursor/rules/claude-mem-context.mdc`
-   - Cursor auto-includes rules with `alwaysApply: true`
-   - Context refreshes on every prompt
-
-2. **Transcript Access**: Cursor hooks don't provide transcript paths
-   - **Impact**: Summary generation less accurate
-   - **Workaround**: Worker generates from observations
-
-3. **SessionStart Hook**: Cursor doesn't have session start event
-   - **Impact**: User message display must be optional
-   - **Workaround**: Can run on `beforeSubmitPrompt` if desired
-
-4. **SDK Agent Session**: Cursor doesn't use SDK agent pattern
-   - **Impact**: No `/sessions/{id}/init` call needed
-   - **Status**: ✅ Not applicable (Cursor-specific)
-
-## Enhancements (Cursor-Specific)
-
-1. **Shell Command Capture**: Maps shell commands to "Bash" tool observations
-   - **Status**: ✅ Enhanced beyond Claude Code
-
-2. **File Edit Capture**: Dedicated hook for file edits
-   - **Status**: ✅ New feature
-
-3. **MCP Tool Capture**: Captures MCP tool usage separately
-   - **Status**: ✅ Enhanced beyond Claude Code
-
-## Summary
-
-| Category | Status |
-|----------|--------|
-| Core Functionality | ✅ Complete parity |
-| Session Management | ✅ Complete parity |
-| Observation Capture | ✅ Complete parity (enhanced) |
-| Context Injection | ✅ Complete parity (via rules file) |
-| Summary Generation | ⚠️ Partial (no transcript) |
-| User Experience | ⚠️ Partial (no SessionStart) |
-
-**Overall**: The Cursor hooks implementation achieves **full functional parity** with claude-mem's Claude Code hooks:
- ✅ Session initialization
- ✅ Context injection (via auto-updated `.cursor/rules/` file)
- ✅ Observation capture (MCP tools, shell commands, file edits)
- ⚠️ Summary generation (works, but no transcript access)
-
@@ -1,112 +0,0 @@
-# Quick Start: Claude-Mem + Cursor Integration
-
-> **Give your Cursor AI persistent memory in under 5 minutes**
-
-## What This Does
-
-Connects claude-mem to Cursor so that:
- **Agent actions** (MCP tools, shell commands, file edits) are automatically saved
- **Context from past sessions** is automatically injected via `.cursor/rules/`
- **Sessions are summarized** for future reference
-
-Your AI stops forgetting. It remembers the patterns, decisions, and context from previous sessions.
-
-## Don't Have Claude Code?
-
-If you're using Cursor without Claude Code, see [STANDALONE-SETUP.md](STANDALONE-SETUP.md) for setup with free-tier providers like Gemini or OpenRouter.
-
---
-
-## Installation (1 minute)
-
-```bash
-# Install globally for all projects (recommended)
-claude-mem cursor install user
-
-# Or install for current project only
-claude-mem cursor install
-
-# Check installation status
-claude-mem cursor status
-```
-
-## Configure Provider (Required for Standalone)
-
-If you don't have Claude Code, configure a provider for AI summarization:
-
-```bash
-# Option A: Gemini (free tier available - recommended)
-claude-mem settings set CLAUDE_MEM_PROVIDER gemini
-claude-mem settings set CLAUDE_MEM_GEMINI_API_KEY your-api-key
-
-# Option B: OpenRouter (free models available)
-claude-mem settings set CLAUDE_MEM_PROVIDER openrouter
-claude-mem settings set CLAUDE_MEM_OPENROUTER_API_KEY your-api-key
-```
-
-**Get free API keys**:
- Gemini: https://aistudio.google.com/apikey
- OpenRouter: https://openrouter.ai/keys
-
-## Start Worker
-
-```bash
-claude-mem start
-
-# Verify it's running
-claude-mem status
-```
-
-## Restart Cursor
-
-Restart Cursor to load the hooks.
-
-## Verify It's Working
-
-1. Open Cursor Settings → Hooks tab
-2. You should see the hooks listed
-3. Submit a prompt in Cursor
-4. Check the web viewer: http://localhost:37777
-5. You should see observations appearing
-
-## What Gets Captured
-
- **MCP Tool Usage**: All MCP tool executions
- **Shell Commands**: All terminal commands
- **File Edits**: All file modifications
- **Sessions**: Each conversation is tracked
-
-## Accessing Memory
-
-### Via Web Viewer
- Open http://localhost:37777
- Browse sessions, observations, and summaries
- Search your project history
-
-### Via MCP Tools (if enabled)
- claude-mem provides search tools via MCP
- Use `search`, `timeline`, and `get_observations` tools
-
-## Troubleshooting
-
-**Hooks not running?**
- Check Cursor Settings → Hooks tab for errors
- Verify scripts are executable: `chmod +x ~/.cursor/hooks/*.sh`
- Check Hooks output channel in Cursor
-
-**Worker not responding?**
- Check if worker is running: `curl http://127.0.0.1:37777/api/readiness`
- Check logs: `tail -f ~/.claude-mem/logs/worker-$(date +%Y-%m-%d).log`
- Restart worker: `bun run worker:restart`
-
-**Observations not saving?**
- Check worker logs for errors
- Verify session was initialized in web viewer
- Test API directly: `curl -X POST http://127.0.0.1:37777/api/sessions/observations ...`
-
-## Next Steps
-
- Read [README.md](README.md) for detailed documentation
- Read [INTEGRATION.md](INTEGRATION.md) for architecture details
- Visit [claude-mem docs](https://docs.claude-mem.ai) for full feature set
-
@@ -1,246 +0,0 @@
-# Claude-Mem Cursor Hooks Integration
-
-> **Persistent AI Memory for Cursor - Free Options Available**
-
-Give your Cursor AI persistent memory across sessions. Your agent remembers what it worked on, the decisions it made, and the patterns in your codebase - automatically.
-
-### Why Claude-Mem?
-
- **Remember context across sessions**: No more re-explaining your codebase every time
- **Automatic capture**: MCP tools, shell commands, and file edits are logged without effort
- **Free tier options**: Works with Gemini (1500 free req/day) or OpenRouter (free models available)
- **Works with or without Claude Code**: Full functionality either way
-
-### Quick Install (5 minutes)
-
-```bash
-# Clone and build
-git clone https://github.com/thedotmack/claude-mem.git
-cd claude-mem && bun install && bun run build
-
-# Interactive setup (configures provider + installs hooks)
-bun run cursor:setup
-```
-
---
-
-## Quick Start for Cursor Users
-
-**Using Claude Code?** Skip to [Installation](#installation) - everything works automatically.
-
-**Cursor-only (no Claude Code)?** See [STANDALONE-SETUP.md](STANDALONE-SETUP.md) for free-tier options using Gemini or OpenRouter.
-
---
-
-## Overview
-
-The hooks bridge Cursor's hook system to claude-mem's worker API, allowing:
- **Session Management**: Initialize sessions and generate summaries
- **Observation Capture**: Record MCP tool usage, shell commands, and file edits
- **Worker Readiness**: Ensure the worker is running before prompt submission
-
-## Context Injection
-
-Context is automatically injected via Cursor's **Rules** system:
-
-1. **Install**: `claude-mem cursor install` generates initial context
-2. **Stop hook**: Updates context in `.cursor/rules/claude-mem-context.mdc` after each session
-3. **Cursor**: Automatically includes this rule in ALL chat sessions
-
-**The context updates after each session ends**, so the next session sees fresh context.
-
-### Additional Access Methods
-
- **MCP Tools**: Configure claude-mem's MCP server for `search`, `timeline`, `get_observations` tools
- **Web Viewer**: Access context at `http://localhost:37777`
- **Manual Request**: Ask the agent to search memory
-
-See [CONTEXT-INJECTION.md](CONTEXT-INJECTION.md) for details.
-
-## Installation
-
-### Quick Install (Recommended)
-
-```bash
-# Install globally for all projects (recommended)
-claude-mem cursor install user
-
-# Or install for current project only
-claude-mem cursor install
-```
-
-### Manual Installation
-
-<details>
-<summary>Click to expand manual installation steps</summary>
-
-**User-level** (recommended - applies to all projects):
-```bash
-# Copy hooks.json to your home directory
-cp cursor-hooks/hooks.json ~/.cursor/hooks.json
-
-# Copy hook scripts
-mkdir -p ~/.cursor/hooks
-cp cursor-hooks/*.sh ~/.cursor/hooks/
-chmod +x ~/.cursor/hooks/*.sh
-```
-
-**Project-level** (for per-project hooks):
-```bash
-# Copy hooks.json to your project
-mkdir -p .cursor
-cp cursor-hooks/hooks.json .cursor/hooks.json
-
-# Copy hook scripts to your project
-mkdir -p .cursor/hooks
-cp cursor-hooks/*.sh .cursor/hooks/
-chmod +x .cursor/hooks/*.sh
-```
-
-</details>
-
-### After Installation
-
-1. **Start the worker**:
-   ```bash
-   claude-mem start
-   ```
-
-2. **Restart Cursor** to load the hooks
-
-3. **Verify installation**:
-   ```bash
-   claude-mem cursor status
-   ```
-
-## Hook Mappings
-
-| Cursor Hook | Script | Purpose |
-|-------------|--------|---------|
-| `beforeSubmitPrompt` | `session-init.sh` | Initialize claude-mem session |
-| `beforeSubmitPrompt` | `context-inject.sh` | Ensure worker is running |
-| `afterMCPExecution` | `save-observation.sh` | Capture MCP tool usage |
-| `afterShellExecution` | `save-observation.sh` | Capture shell command execution |
-| `afterFileEdit` | `save-file-edit.sh` | Capture file edits |
-| `stop` | `session-summary.sh` | Generate summary + update context file |
-
-## How It Works
-
-### Session Initialization (`session-init.sh`)
- Called before each prompt submission
- Initializes a new session in claude-mem using `conversation_id` as the session ID
- Extracts project name from workspace root
- Outputs `{"continue": true}` to allow prompt submission
-
-### Context Hook (`context-inject.sh`)
- Ensures claude-mem worker is running before session
- Outputs `{"continue": true}` to allow prompt submission
- Note: Context file is updated by `session-summary.sh` (stop hook), not here
-
-### Observation Capture (`save-observation.sh`)
- Captures MCP tool executions and shell commands
- Maps them to claude-mem's observation format
- Sends to `/api/sessions/observations` endpoint (fire-and-forget)
-
-### File Edit Capture (`save-file-edit.sh`)
- Captures file edits made by the agent
- Treats edits as "write_file" tool usage
- Includes edit summaries in observations
-
-### Session Summary (`session-summary.sh`)
- Called when agent loop ends (stop hook)
- Requests summary generation from claude-mem
- **Updates context file** in `.cursor/rules/claude-mem-context.mdc` for next session
-
-## Configuration
-
-The hooks read configuration from `~/.claude-mem/settings.json`:
-
- `CLAUDE_MEM_WORKER_PORT`: Worker port (default: 37777)
- `CLAUDE_MEM_WORKER_HOST`: Worker host (default: 127.0.0.1)
-
-## Dependencies
-
-The hook scripts require:
- `jq` - JSON processing
- `curl` - HTTP requests
- `bash` - Shell interpreter
-
-Install on macOS: `brew install jq curl`
-Install on Ubuntu: `apt-get install jq curl`
-
-## Troubleshooting
-
-### Hooks not executing
-
-1. Check hooks are in the correct location:
-   ```bash
-   ls .cursor/hooks.json  # Project-level
-   ls ~/.cursor/hooks.json  # User-level
-   ```
-
-2. Verify scripts are executable:
-   ```bash
-   chmod +x ~/.cursor/hooks/*.sh
-   ```
-
-3. Check Cursor Settings → Hooks tab for configuration status
-
-4. Check Hooks output channel in Cursor for error messages
-
-### Worker not responding
-
-1. Verify worker is running:
-   ```bash
-   curl http://127.0.0.1:37777/api/readiness
-   ```
-
-2. Check worker logs:
-   ```bash
-   tail -f ~/.claude-mem/logs/worker-$(date +%Y-%m-%d).log
-   ```
-
-3. Restart worker:
-   ```bash
-   claude-mem restart
-   ```
-
-### Observations not being saved
-
-1. Monitor worker logs for incoming requests
-
-2. Verify session was initialized via web viewer at `http://localhost:37777`
-
-3. Test observation endpoint directly:
-   ```bash
-   curl -X POST http://127.0.0.1:37777/api/sessions/observations \
-     -H "Content-Type: application/json" \
-     -d '{"contentSessionId":"test","tool_name":"test","tool_input":{},"tool_response":{},"cwd":"/tmp"}'
-   ```
-
-## Comparison with Claude Code Integration
-
-| Feature | Claude Code | Cursor |
-|---------|-------------|--------|
-| Session Initialization | ✅ `SessionStart` hook | ✅ `beforeSubmitPrompt` hook |
-| Context Injection | ✅ `additionalContext` field | ✅ Auto-updated `.cursor/rules/` file |
-| Observation Capture | ✅ `PostToolUse` hook | ✅ `afterMCPExecution`, `afterShellExecution`, `afterFileEdit` |
-| Session Summary | ✅ `Stop` hook with transcript | ⚠️ `stop` hook (no transcript) |
-| MCP Search Tools | ✅ Full support | ✅ Full support (if MCP configured) |
-
-## Files
-
- `hooks.json` - Hook configuration
- `common.sh` - Shared utility functions
- `session-init.sh` - Session initialization
- `context-inject.sh` - Context/worker readiness hook
- `save-observation.sh` - MCP and shell observation capture
- `save-file-edit.sh` - File edit observation capture
- `session-summary.sh` - Summary generation
- `cursorrules-template.md` - Template for `.cursorrules` file
-
-## See Also
-
- [Claude-Mem Documentation](https://docs.claude-mem.ai)
- [Cursor Hooks Reference](../docs/context/cursor-hooks-reference.md)
- [Claude-Mem Architecture](https://docs.claude-mem.ai/architecture/overview)
@@ -1,327 +0,0 @@
-# Comprehensive Review: Cursor Hooks Integration
-
-## Overview
-
-This document provides a thorough review of the Cursor hooks integration, covering all aspects from implementation details to edge cases and potential issues.
-
-## Architecture Review
-
-### ✅ Strengths
-
-1. **Modular Design**: Common utilities extracted to `common.sh` for reusability
-2. **Error Handling**: Graceful degradation - hooks never block Cursor even on failures
-3. **Parity with Claude Code**: Matches claude-mem's hook behavior where possible
-4. **Fire-and-Forget**: Observations sent asynchronously, don't block agent execution
-
-### ⚠️ Limitations (Platform-Specific)
-
-1. **No Windows Support**: Bash scripts require Unix-like environment
-   - **Mitigation**: Could add PowerShell equivalents or use Node.js/Python wrappers
-2. **Dependency on jq/curl**: Requires external tools
-   - **Mitigation**: Dependency checks added, graceful fallback
-
-## Script-by-Script Review
-
-### 1. `common.sh` - Utility Functions
-
-**Purpose**: Shared utilities for all hook scripts
-
-**Functions**:
- ✅ `check_dependencies()` - Validates jq and curl exist
- ✅ `read_json_input()` - Safely reads and validates JSON from stdin
- ✅ `get_worker_port()` - Reads port from settings with validation
- ✅ `ensure_worker_running()` - Health checks with retries
- ✅ `url_encode()` - URL encoding for special characters
- ✅ `get_project_name()` - Extracts project name with edge case handling
- ✅ `json_get()` - Safe JSON field extraction with array support
- ✅ `is_empty()` - Null/empty string detection
-
-**Edge Cases Handled**:
- ✅ Empty stdin
- ✅ Malformed JSON
- ✅ Missing settings file
- ✅ Invalid port numbers
- ✅ Windows drive roots (C:\, etc.)
- ✅ Empty workspace roots
- ✅ Array field access (`workspace_roots[0]`)
-
-**Potential Issues**:
- ⚠️ `url_encode()` uses jq - if jq fails, encoding fails silently
- ✅ **Fixed**: Falls back to original string if encoding fails
-
-### 2. `session-init.sh` - Session Initialization
-
-**Purpose**: Initialize claude-mem session when prompt is submitted
-
-**Flow**:
-1. Read and validate JSON input
-2. Extract session_id, project, prompt
-3. Ensure worker is running
-4. Strip leading slash from prompt (parity with new-hook.ts)
-5. Call `/api/sessions/init`
-6. Handle privacy checks
-
-**Edge Cases Handled**:
- ✅ Empty conversation_id → fallback to generation_id
- ✅ Empty workspace_root → fallback to pwd
- ✅ Empty prompt → still initializes session
- ✅ Worker unavailable → graceful exit
- ✅ Privacy-skipped sessions → silent exit
- ✅ Invalid JSON → graceful exit
-
-**Potential Issues**:
- ✅ **Fixed**: String slicing now checks for empty strings
- ✅ **Fixed**: All jq operations have error handling
- ✅ **Fixed**: Worker health check with proper retries
-
-**Parity with Claude Code**:
- ✅ Session initialization
- ✅ Privacy check handling
- ✅ Slash stripping
- ❌ SDK agent init (not applicable to Cursor)
-
-### 3. `save-observation.sh` - Observation Capture
-
-**Purpose**: Capture MCP tool usage and shell commands
-
-**Flow**:
-1. Read and validate JSON input
-2. Determine hook type (MCP vs Shell)
-3. Extract tool data
-4. Validate JSON structures
-5. Ensure worker is running
-6. Send observation (fire-and-forget)
-
-**Edge Cases Handled**:
- ✅ Empty tool_name → exit gracefully
- ✅ Invalid tool_input/tool_response → default to {}
- ✅ Malformed JSON in tool data → validated and sanitized
- ✅ Empty session_id → exit gracefully
- ✅ Worker unavailable → exit gracefully
-
-**Potential Issues**:
- ✅ **Fixed**: JSON validation for tool_input and tool_response
- ✅ **Fixed**: Proper handling of empty/null values
- ✅ **Fixed**: Error handling for all jq operations
-
-**Parity with Claude Code**:
- ✅ Tool observation capture
- ✅ Privacy tag stripping (handled by worker)
- ✅ Fire-and-forget pattern
- ✅ Enhanced: Shell command capture (not in Claude Code)
-
-### 4. `save-file-edit.sh` - File Edit Capture
-
-**Purpose**: Capture file edits as observations
-
-**Flow**:
-1. Read and validate JSON input
-2. Extract file_path and edits array
-3. Validate edits array
-4. Create edit summary
-5. Ensure worker is running
-6. Send observation (fire-and-forget)
-
-**Edge Cases Handled**:
- ✅ Empty file_path → exit gracefully
- ✅ Empty edits array → exit gracefully
- ✅ Invalid edits JSON → default to []
- ✅ Malformed edit objects → summary generation handles gracefully
- ✅ Empty session_id → exit gracefully
-
-**Potential Issues**:
- ✅ **Fixed**: Edit summary generation with error handling
- ✅ **Fixed**: Array validation before processing
- ✅ **Fixed**: Safe string slicing in summary generation
-
-**Parity with Claude Code**:
- ✅ File edit capture (new feature for Cursor)
- ✅ Observation format matches claude-mem structure
-
-### 5. `session-summary.sh` - Summary Generation
-
-**Purpose**: Generate session summary when agent loop ends
-
-**Flow**:
-1. Read and validate JSON input
-2. Extract session_id
-3. Ensure worker is running
-4. Send summarize request with empty messages (no transcript access)
-5. Output empty JSON (required by Cursor)
-
-**Edge Cases Handled**:
- ✅ Empty session_id → exit gracefully
- ✅ Worker unavailable → exit gracefully
- ✅ Missing transcript → empty messages (worker handles gracefully)
-
-**Potential Issues**:
- ✅ **Fixed**: Proper JSON output for Cursor stop hook
- ✅ **Fixed**: Worker handles empty messages (verified in codebase)
-
-**Parity with Claude Code**:
- ⚠️ Partial: No transcript access, so no last_user_message/last_assistant_message
- ✅ Summary generation still works (based on observations)
-
-### 6. `context-inject.sh` - Context Injection via Rules File
-
-**Purpose**: Fetch context and write to `.cursor/rules/` for auto-injection
-
-**How It Works**:
-1. Fetches context from claude-mem worker
-2. Writes to `.cursor/rules/claude-mem-context.mdc` with `alwaysApply: true`
-3. Cursor auto-includes this rule in all chat sessions
-4. Context refreshes on every prompt submission
-
-**Flow**:
-1. Read and validate JSON input
-2. Extract workspace root
-3. Get project name
-4. Ensure worker is running
-5. Fetch context from `/api/context/inject`
-6. Write context to `.cursor/rules/claude-mem-context.mdc`
-7. Output `{"continue": true}`
-
-**Edge Cases Handled**:
- ✅ Empty workspace_root → fallback to pwd
- ✅ Worker unavailable → allow prompt to continue
- ✅ Context fetch failure → allow prompt to continue (no file written)
- ✅ Special characters in project name → URL encoded
- ✅ Missing `.cursor/rules/` directory → created automatically
-
-**Parity with Claude Code**:
- ✅ Context injection achieved via rules file workaround
- ✅ Worker readiness check matches Claude Code
- ✅ Context available immediately in next prompt
-
-## Error Handling Review
-
-### ✅ Comprehensive Error Handling
-
-1. **Input Validation**:
-   - ✅ Empty stdin → default to `{}`
-   - ✅ Malformed JSON → validated and sanitized
-   - ✅ Missing fields → safe fallbacks
-
-2. **Dependency Checks**:
-   - ✅ jq and curl existence checked
-   - ✅ Non-blocking (warns but continues)
-
-3. **Network Errors**:
-   - ✅ Worker unavailable → graceful exit
-   - ✅ HTTP failures → fire-and-forget (don't block)
-   - ✅ Timeout handling → 15 second retries
-
-4. **Data Validation**:
-   - ✅ Port number validation (1-65535)
-   - ✅ JSON structure validation
-   - ✅ Empty/null value handling
-
-## Security Review
-
-### ✅ Security Considerations
-
-1. **Input Sanitization**:
-   - ✅ JSON validation prevents injection
-   - ✅ URL encoding for special characters
-   - ✅ Worker handles privacy tag stripping
-
-2. **Error Information**:
-   - ✅ Errors don't expose sensitive data
-   - ✅ Fire-and-forget prevents information leakage
-
-3. **Dependency Security**:
-   - ✅ Uses standard tools (jq, curl)
-   - ✅ No custom code execution
-
-## Performance Review
-
-### ✅ Performance Optimizations
-
-1. **Non-Blocking**:
-   - ✅ All hooks exit quickly (don't block Cursor)
-   - ✅ Observations sent asynchronously
-
-2. **Efficient Health Checks**:
-   - ✅ 200ms polling interval
-   - ✅ 15 second maximum wait
-   - ✅ Early exit on success
-
-3. **Resource Usage**:
-   - ✅ Minimal memory footprint
-   - ✅ No long-running processes
-   - ✅ Fire-and-forget HTTP requests
-
-## Testing Recommendations
-
-### Unit Tests Needed
-
-1. **common.sh functions**:
-   - [ ] Test `json_get()` with various field types
-   - [ ] Test `get_project_name()` with edge cases
-   - [ ] Test `url_encode()` with special characters
-   - [ ] Test `ensure_worker_running()` with various states
-
-2. **Hook scripts**:
-   - [ ] Test with empty input
-   - [ ] Test with malformed JSON
-   - [ ] Test with missing fields
-   - [ ] Test with worker unavailable
-   - [ ] Test with invalid port numbers
-
-### Integration Tests Needed
-
-1. **End-to-end flow**:
-   - [ ] Session initialization → observation capture → summary
-   - [ ] Multiple concurrent hooks
-   - [ ] Worker restart scenarios
-
-2. **Edge cases**:
-   - [ ] Very long prompts/commands
-   - [ ] Special characters in paths
-   - [ ] Unicode in tool inputs
-   - [ ] Large file edits
-
-## Known Limitations
-
-1. **Cursor Hook System**:
-   - ✅ Context injection solved via `.cursor/rules/` file
-   - ❌ No transcript access for summary generation
-   - ❌ No SessionStart equivalent
-
-2. **Platform Support**:
-   - ⚠️ Bash scripts (Unix-like only)
-   - ⚠️ Requires jq and curl
-
-3. **Context Injection**:
-   - ✅ Solved via auto-updated `.cursor/rules/claude-mem-context.mdc`
-   - ✅ Context also available via MCP tools
-   - ✅ Context also available via web viewer
-
-## Recommendations
-
-### Immediate Improvements
-
-1. ✅ **DONE**: Comprehensive error handling
-2. ✅ **DONE**: Input validation
-3. ✅ **DONE**: Dependency checks
-4. ✅ **DONE**: URL encoding
-
-### Future Enhancements
-
-1. **Logging**: Add optional debug logging to help troubleshoot
-2. **Metrics**: Track hook execution times and success rates
-3. **Windows Support**: PowerShell or Node.js equivalents
-4. **Testing**: Automated test suite
-5. **Documentation**: More examples and troubleshooting guides
-
-## Conclusion
-
-The Cursor hooks integration is **production-ready** with:
- ✅ Comprehensive error handling
- ✅ Input validation and sanitization
- ✅ Graceful degradation
- ✅ Feature parity with Claude Code hooks (where applicable)
- ✅ Enhanced features (shell/file edit capture)
-
-The implementation handles edge cases well and follows best practices for reliability and maintainability.
-
@@ -1,293 +0,0 @@
-# Claude-Mem for Cursor (No Claude Code Required)
-
-> **Persistent AI Memory for Cursor - Zero Cost to Start**
-
-## Overview
-
-Use claude-mem's persistent memory in Cursor without a Claude Code subscription. Choose between free-tier providers (Gemini, OpenRouter) or paid options.
-
-**What You Get**:
- **Persistent memory** that survives across sessions - your AI remembers what it worked on
- **Automatic capture** of MCP tools, shell commands, and file edits
- **Context injection** via `.cursor/rules/` - relevant history included in every chat
- **Web viewer** at http://localhost:37777 - browse and search your project history
-
-**Why This Matters**: Every Cursor session starts fresh. Claude-mem bridges that gap - your AI agent builds cumulative knowledge about your codebase, decisions, and patterns over time.
-
-## Prerequisites
-
-### macOS / Linux
- Cursor IDE
- [Bun](https://bun.sh) (`curl -fsSL https://bun.sh/install | bash`)
- Git
- `jq` and `curl`:
-  - **macOS**: `brew install jq curl`
-  - **Linux**: `apt install jq curl`
-
-### Windows
- Cursor IDE
- [Bun](https://bun.sh) (PowerShell: `powershell -c "irm bun.sh/install.ps1 | iex"`)
- Git
- PowerShell 5.1+ (included with Windows 10/11)
-
-## Step 1: Clone Claude-Mem
-
-```bash
-# Clone the repository
-git clone https://github.com/thedotmack/claude-mem.git
-cd claude-mem
-
-# Install dependencies
-bun install
-
-# Build the project
-bun run build
-```
-
-## Step 2: Configure Provider (Choose One)
-
-Since you don't have Claude Code, you need to configure an AI provider for claude-mem's summarization engine.
-
-### Option A: Gemini (Recommended - Free Tier)
-
-Gemini offers 1500 free requests per day, plenty for typical usage.
-
-```bash
-# Create settings directory
-mkdir -p ~/.claude-mem
-
-# Create settings file
-cat > ~/.claude-mem/settings.json << 'EOF'
-{
-  "CLAUDE_MEM_PROVIDER": "gemini",
-  "CLAUDE_MEM_GEMINI_API_KEY": "YOUR_GEMINI_API_KEY",
-  "CLAUDE_MEM_GEMINI_MODEL": "gemini-2.5-flash-lite",
-  "CLAUDE_MEM_GEMINI_RATE_LIMITING_ENABLED": true
-}
-EOF
-```
-
-**Get your free API key**: https://aistudio.google.com/apikey
-
-### Option B: OpenRouter (100+ Models)
-
-OpenRouter provides access to many models, including free options.
-
-```bash
-mkdir -p ~/.claude-mem
-cat > ~/.claude-mem/settings.json << 'EOF'
-{
-  "CLAUDE_MEM_PROVIDER": "openrouter",
-  "CLAUDE_MEM_OPENROUTER_API_KEY": "YOUR_OPENROUTER_API_KEY"
-}
-EOF
-```
-
-**Get your API key**: https://openrouter.ai/keys
-
-**Free models available**:
- `google/gemini-2.0-flash-exp:free`
- `xiaomi/mimo-v2-flash:free`
-
-### Option C: Claude API (If You Have API Access)
-
-If you have Anthropic API credits but not a Claude Code subscription:
-
-```bash
-mkdir -p ~/.claude-mem
-cat > ~/.claude-mem/settings.json << 'EOF'
-{
-  "CLAUDE_MEM_PROVIDER": "claude",
-  "ANTHROPIC_API_KEY": "YOUR_ANTHROPIC_API_KEY"
-}
-EOF
-```
-
-## Step 3: Install Cursor Hooks
-
-```bash
-# From the claude-mem repo directory (recommended - all projects)
-bun run cursor:install -- user
-
-# Or for project-level only:
-bun run cursor:install
-```
-
-This installs:
- Hook scripts to `.cursor/hooks/`
- Hook configuration to `.cursor/hooks.json`
- Context template to `.cursor/rules/`
-
-## Step 4: Start the Worker
-
-```bash
-bun run worker:start
-```
-
-The worker runs in the background and handles:
- Session management
- Observation processing
- AI-powered summarization
- Context file updates
-
-## Step 5: Restart Cursor & Verify
-
-1. **Restart Cursor IDE** to load the new hooks
-
-2. **Check installation status**:
-   ```bash
-   bun run cursor:status
-   ```
-
-3. **Verify the worker is running**:
-   ```bash
-   curl http://127.0.0.1:37777/api/readiness
-   ```
-   Should return: `{"status":"ready"}`
-
-4. **Open the web viewer**: http://localhost:37777
-
-## How It Works
-
-1. **Before each prompt**: Hooks initialize a session and ensure the worker is running
-2. **During agent work**: MCP tools, shell commands, and file edits are captured
-3. **When agent stops**: Summary is generated and context file is updated
-4. **Next session**: Fresh context is automatically injected via `.cursor/rules/`
-
-## Troubleshooting
-
-### "No provider configured" error
-
-Verify your settings file exists and has valid credentials:
-```bash
-cat ~/.claude-mem/settings.json
-```
-
-### Worker not starting
-
-Check logs:
-```bash
-tail -f ~/.claude-mem/logs/worker-$(date +%Y-%m-%d).log
-```
-
-### Hooks not executing
-
-1. Check Cursor Settings → Hooks tab for errors
-2. Verify scripts are executable:
-   ```bash
-   chmod +x ~/.cursor/hooks/*.sh
-   ```
-3. Check the Hooks output channel in Cursor
-
-### Rate limiting (Gemini free tier)
-
-If you hit the 1500 requests/day limit:
- Wait until the next day
- Upgrade to a paid plan
- Switch to OpenRouter with a paid model
-
-## Next Steps
-
- Read [README.md](README.md) for detailed hook documentation
- Check [CONTEXT-INJECTION.md](CONTEXT-INJECTION.md) for context behavior details
- Visit https://docs.claude-mem.ai for full documentation
-
-## Quick Reference
-
-| Command | Purpose |
-|---------|---------|
-| `bun run cursor:install -- user` | Install hooks for all projects (recommended) |
-| `bun run cursor:install` | Install hooks for current project only |
-| `bun run cursor:status` | Check installation status |
-| `bun run worker:start` | Start the background worker |
-| `bun run worker:stop` | Stop the background worker |
-| `bun run worker:restart` | Restart the worker |
-
---
-
-## Windows Installation
-
-Windows users get full support via PowerShell scripts. The installer automatically detects Windows and installs the appropriate scripts.
-
-### Enable Script Execution (if needed)
-
-PowerShell may require you to enable script execution:
-
-```powershell
-Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser
-```
-
-### Step-by-Step for Windows
-
-```powershell
-# Clone and build
-git clone https://github.com/thedotmack/claude-mem.git
-cd claude-mem
-bun install
-bun run build
-
-# Configure provider (Gemini example)
-$settingsDir = "$env:USERPROFILE\.claude-mem"
-New-Item -ItemType Directory -Force -Path $settingsDir
-
-@"
-{
-  "CLAUDE_MEM_PROVIDER": "gemini",
-  "CLAUDE_MEM_GEMINI_API_KEY": "YOUR_GEMINI_API_KEY"
-}
-"@ | Out-File -FilePath "$settingsDir\settings.json" -Encoding UTF8
-
-# Interactive setup (recommended - walks you through everything)
-bun run cursor:setup
-
-# Or manual installation
-bun run cursor:install
-bun run worker:start
-```
-
-### What Gets Installed on Windows
-
-The installer copies these PowerShell scripts to `.cursor\hooks\`:
-
-| Script | Purpose |
-|--------|---------|
-| `common.ps1` | Shared utilities |
-| `session-init.ps1` | Initialize session on prompt |
-| `context-inject.ps1` | Inject memory context |
-| `save-observation.ps1` | Capture MCP/shell usage |
-| `save-file-edit.ps1` | Capture file edits |
-| `session-summary.ps1` | Generate summary on stop |
-
-The `hooks.json` file is configured to invoke PowerShell with `-ExecutionPolicy Bypass` to ensure scripts run without additional configuration.
-
-### Windows Troubleshooting
-
-**"Execution of scripts is disabled on this system"**
-
-Run as Administrator:
-```powershell
-Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope LocalMachine
-```
-
-**PowerShell scripts not running**
-
-Verify the hooks.json contains PowerShell invocations:
-```powershell
-Get-Content .cursor\hooks.json
-```
-
-Should show commands like:
-```
-powershell.exe -ExecutionPolicy Bypass -File "./.cursor/hooks/session-init.ps1"
-```
-
-**Worker not responding**
-
-Check if port 37777 is in use:
-```powershell
-Get-NetTCPConnection -LocalPort 37777
-```
-
-**Antivirus blocking scripts**
-
-Some antivirus software may block PowerShell scripts. Add an exception for the `.cursor\hooks\` directory if needed.
@@ -1,84 +0,0 @@
-# Claude-Mem Rules for Cursor
-
-## Automatic Context Injection
-
-The `context-inject.sh` hook **automatically creates and updates** a rules file at:
-
-```
-.cursor/rules/claude-mem-context.mdc
-```
-
-This file:
- Has `alwaysApply: true` so it's included in every chat session
- Contains recent context from past sessions
- Auto-refreshes on every prompt submission
-
-**You don't need to manually create any rules file!**
-
-## Optional: Additional Instructions
-
-If you want to add custom instructions about claude-mem (beyond the auto-injected context), create a separate rules file:
-
-### `.cursor/rules/claude-mem-instructions.mdc`
-
-```markdown
---
-alwaysApply: true
-description: "Instructions for using claude-mem memory system"
---
-
-# Memory System Usage
-
-You have access to claude-mem, a persistent memory system. In addition to the auto-injected context above, you can search for more detailed information using MCP tools:
-
-## Available MCP Tools
-
-1. **search** - Find relevant past observations
-   ```
-   search(query="authentication bug", project="my-project", limit=10)
-   ```
-
-2. **timeline** - Get context around a specific observation
-   ```
-   timeline(anchor=<observation_id>, depth_before=3, depth_after=3)
-   ```
-
-3. **get_observations** - Fetch full details for specific IDs
-   ```
-   get_observations(ids=[123, 456])
-   ```
-
-## When to Search Memory
-
- When the user asks about previous work or decisions
- When encountering unfamiliar code patterns in this project
- When debugging issues that might have been addressed before
- When asked to continue or build upon previous work
-
-## 3-Layer Workflow
-
-Follow this pattern for token efficiency:
-1. **Search first** - Get compact index (~50-100 tokens/result)
-2. **Timeline** - Get chronological context around interesting results
-3. **Fetch details** - Only for relevant observations (~500-1000 tokens/result)
-
-Never fetch full details without filtering first.
-```
-
-## File Locations
-
-| File | Purpose | Created By |
-|------|---------|------------|
-| `.cursor/rules/claude-mem-context.mdc` | Auto-injected context | Hook (automatic) |
-| `.cursor/rules/claude-mem-instructions.mdc` | MCP tool instructions | You (optional) |
-
-## Git Ignore
-
-If you don't want to commit the auto-generated context file:
-
-```gitignore
-# .gitignore
-.cursor/rules/claude-mem-context.mdc
-```
-
-The instructions file can be committed to share with your team.
@@ -1,34 +0,0 @@
-{
-  "version": 1,
-  "hooks": {
-    "beforeSubmitPrompt": [
-      {
-        "command": "./cursor-hooks/session-init.sh"
-      },
-      {
-        "command": "./cursor-hooks/context-inject.sh"
-      }
-    ],
-    "afterMCPExecution": [
-      {
-        "command": "./cursor-hooks/save-observation.sh"
-      }
-    ],
-    "afterShellExecution": [
-      {
-        "command": "./cursor-hooks/save-observation.sh"
-      }
-    ],
-    "afterFileEdit": [
-      {
-        "command": "./cursor-hooks/save-file-edit.sh"
-      }
-    ],
-    "stop": [
-      {
-        "command": "./cursor-hooks/session-summary.sh"
-      }
-    ]
-  }
-}
-
@@ -1,83 +0,0 @@
-<claude-mem-context>
-# Recent Activity
-
-<!-- This section is auto-generated by claude-mem. Edit content outside the tags. -->
-
-### Nov 6, 2025
-
-| ID | Time | T | Title | Read |
-|----|------|---|-------|------|
-| #4241 | 11:19 PM | 🟣 | Object-Oriented Architecture Design Document Created | ~662 |
-| #4240 | 11:11 PM | 🟣 | Worker Service Rewrite Blueprint Created | ~541 |
-| #4239 | 11:07 PM | 🟣 | Comprehensive Worker Service Performance Analysis Document Created | ~541 |
-| #4238 | 10:59 PM | 🔵 | Overhead Analysis Document Checked | ~203 |
-
-### Nov 7, 2025
-
-| ID | Time | T | Title | Read |
-|----|------|---|-------|------|
-| #4609 | 6:33 PM | ✅ | PR #69 Successfully Merged to Main Branch | ~516 |
-| #4600 | 6:31 PM | 🟣 | Added Worker Service Documentation Suite | ~441 |
-| #4597 | " | 🔄 | Worker Service Refactored to Object-Oriented Architecture | ~473 |
-
-### Nov 8, 2025
-
-| ID | Time | T | Title | Read |
-|----|------|---|-------|------|
-| #5539 | 10:20 PM | 🔵 | Harsh critical audit of context-hook reveals systematic anti-patterns | ~3154 |
-| #5497 | 9:29 PM | 🔵 | Harsh critical audit of context-hook reveals systematic anti-patterns | ~2815 |
-| #5495 | 9:28 PM | 🔵 | Context Hook Audit Reveals Project Anti-Patterns | ~660 |
-| #5476 | 9:17 PM | 🔵 | Critical Code Audit Identified 14 Anti-Patterns in Context Hook | ~887 |
-| #5391 | 8:45 PM | 🔵 | Critical Code Quality Audit of Context Hook Implementation | ~720 |
-| #5150 | 7:37 PM | 🟣 | Troubleshooting Skill Added to Claude-Mem Plugin | ~427 |
-
-### Nov 9, 2025
-
-| ID | Time | T | Title | Read |
-|----|------|---|-------|------|
-| #6161 | 11:55 PM | 🔵 | YC W26 Application Research and Preparation Completed for Claude-Mem | ~1628 |
-| #6155 | 11:47 PM | ✅ | Comprehensive Y Combinator Winter 2026 Application Notes Created | ~1045 |
-| #5979 | 7:58 PM | 🔵 | Smart Contextualization Feature Architecture | ~560 |
-| #5971 | 7:49 PM | 🔵 | Hooks Reference Documentation Structure | ~448 |
-| #5929 | 7:08 PM | ✅ | Documentation Updates for v5.4.0 Skill-Based Search Migration | ~604 |
-| #5927 | " | ✅ | Updated Configuration Documentation for Skill-Based Search | ~497 |
-| #5920 | 7:05 PM | ✅ | Renamed Architecture Documentation File Reference | ~271 |
-
-### Nov 18, 2025
-
-| ID | Time | T | Title | Read |
-|----|------|---|-------|------|
-| #11515 | 8:22 PM | 🔵 | Smart Contextualization Architecture Retrieved with Command Hook Pattern Details | ~502 |
-
-### Dec 8, 2025
-
-| ID | Time | T | Title | Read |
-|----|------|---|-------|------|
-| #22294 | 9:43 PM | 🔵 | Documentation Site Structure Located | ~359 |
-
-### Dec 12, 2025
-
-| ID | Time | T | Title | Read |
-|----|------|---|-------|------|
-| #24430 | 8:27 PM | ✅ | Removed Final Platform Check Reference from Linux Section | ~320 |
-| #24429 | " | ✅ | Final Platform Check Reference Removal from Linux Section | ~274 |
-| #24428 | " | ✅ | Corrected Second Line Number Reference for Migration Marker Logic | ~267 |
-| #24427 | 8:26 PM | ✅ | Updated Line Number Reference for PM2 Cleanup Implementation | ~260 |
-| #24426 | " | ✅ | Removed Platform Check from Manual Marker Deletion Scenario | ~338 |
-| #24425 | " | ✅ | Removed Platform Check from Fresh Install Scenario Flow | ~314 |
-| #24424 | 8:25 PM | ✅ | Renumbered Manual Marker Deletion Scenario | ~285 |
-| #24423 | " | ✅ | Renumbered Fresh Install Scenario | ~243 |
-| #24422 | " | ✅ | Removed Obsolete Windows Platform Detection Scenario | ~311 |
-| #24421 | " | ✅ | Removed Platform Check from macOS Migration Documentation | ~294 |
-| #24420 | 8:24 PM | ✅ | Platform Check Removed from Migration Documentation | ~288 |
-| #24417 | 8:16 PM | ✅ | Code Reference Example Updated to Reflect Actual Cross-Platform Implementation | ~366 |
-| #24416 | " | ✅ | Architecture Decision Documentation Updated to Reflect Cross-Platform PM2 Cleanup Rationale | ~442 |
-| #24415 | 8:15 PM | ✅ | Migration Marker Lifecycle Documentation Updated for Unified Cross-Platform Behavior | ~463 |
-| #24414 | " | ✅ | Platform Comparison Table Updated to Reflect Unified Cross-Platform Migration | ~351 |
-| #24413 | " | ✅ | Windows Platform-Specific Documentation Completely Rewritten for Unified Migration | ~428 |
-| #24412 | " | ✅ | User Experience Timeline Updated for Cross-Platform PM2 Cleanup | ~291 |
-| #24411 | 8:14 PM | ✅ | Migration Marker Lifecycle Documentation Updated for All Platforms | ~277 |
-| #24410 | " | ✅ | Marker File Platform Behavior Documentation Updated for Unified Migration | ~282 |
-| #24409 | " | ✅ | Migration Steps Documentation Updated for Cross-Platform PM2 Cleanup | ~278 |
-| #24408 | 8:13 PM | ✅ | PM2 Migration Documentation Updated to Remove Windows Platform Check | ~280 |
-</claude-mem-context>
@@ -1,213 +0,0 @@
-# Claude-Mem PR Shipping Report
-*Generated: 2026-02-04*
-
-## Executive Summary
-
-6 PRs analyzed for shipping readiness. **1 is ready to merge**, 4 have conflicts, 1 is too large for easy review.
-
-| PR | Title | Status | Recommendation |
-|----|-------|--------|----------------|
-| **#856** | Idle timeout for zombie processes | ✅ **MERGEABLE** | **Ship it** |
-| #700 | Windows Terminal popup fix | ⚠️ Conflicts | Rebase, then ship |
-| #722 | In-process worker architecture | ⚠️ Conflicts | Rebase, high impact |
-| #657 | generate/clean CLI commands | ⚠️ Conflicts | Rebase, then ship |
-| #863 | Ragtime email investigation | 🔍 Needs review | Research pending |
-| #464 | Sleep Agent Pipeline (contributor) | 🔴 Too large | Request split or dedicated review |
-
---
-
-## Ready to Ship
-
-### PR #856: Idle Timeout for Zombie Observer Processes
-**Status:** ✅ MERGEABLE (no conflicts)
-
-| Metric | Value |
-|--------|-------|
-| Additions | 928 |
-| Deletions | 171 |
-| Files | 8 |
-| Risk | Low-Medium |
-
-**What it does:**
- Adds 3-minute idle timeout to `SessionQueueProcessor`
- Prevents zombie observer processes that were causing 13.4GB swap usage
- Processes exit gracefully after inactivity instead of waiting forever
-
-**Why ship it:**
- Fixes real user-reported issue (79 zombie processes)
- Well-tested (11 new tests, 440 lines of test coverage)
- Clean implementation, preventive approach
- Supersedes PR #848's reactive cleanup
- No conflicts, ready to merge
-
-**Review notes:**
- 1 Greptile bot comment (addressed)
- Race condition fix included
- Enhanced logging added
-
---
-
-## Needs Rebase (Have Conflicts)
-
-### PR #700: Windows Terminal Popup Fix
-**Status:** ⚠️ CONFLICTING
-
-| Metric | Value |
-|--------|-------|
-| Additions | 187 |
-| Deletions | 399 |
-| Files | 8 |
-| Risk | Medium |
-
-**What it does:**
- Eliminates Windows Terminal popup by removing spawn-based daemon
- Worker `start` command becomes daemon directly (no child spawn)
- Removes `restart` command (users do `stop` then `start`)
- Net simplification: -212 lines
-
-**Breaking changes:**
- `restart` command removed
-
-**Review status:**
- ✅ 1 APPROVAL from @volkanfirat (Jan 15, 2026)
-
-**Action needed:** Resolve conflicts, then ready to ship.
-
---
-
-### PR #722: In-Process Worker Architecture
-**Status:** ⚠️ CONFLICTING
-
-| Metric | Value |
-|--------|-------|
-| Additions | 869 |
-| Deletions | 4,658 |
-| Files | 112 |
-| Risk | High |
-
-**What it does:**
- Hook processes become the worker (no separate daemon spawning)
- First hook that needs worker becomes the worker
- Eliminates Windows spawn issues ("NO SPAWN" rule)
- 761 tests pass
-
-**Architectural impact:** HIGH
- Fundamentally changes worker lifecycle
- Hook processes stay alive (they ARE the worker)
- First hook wins port 37777, others use HTTP
-
-**Action needed:** Resolve conflicts. Consider relationship with PR #700 (both touch worker architecture).
-
---
-
-### PR #657: Generate/Clean CLI Commands
-**Status:** ⚠️ CONFLICTING
-
-| Metric | Value |
-|--------|-------|
-| Additions | 1,184 |
-| Deletions | 5,057 |
-| Files | 104 |
-| Risk | Medium |
-
-**What it does:**
- Adds `claude-mem generate` and `claude-mem clean` CLI commands
- Fixes validation bugs (deleted folders recreated from stale DB)
- Fixes Windows path handling
- Adds automatic shell alias installation
- Disables subdirectory CLAUDE.md files by default
-
-**Breaking changes:**
- Default behavior change: folder CLAUDE.md now disabled by default
-
-**Action needed:** Resolve conflicts, complete Windows testing.
-
---
-
-## Needs Attention
-
-### PR #863: Ragtime Email Investigation
-**Status:** 🔍 Research pending
-
-Research agent did not return results. Manual review needed.
-
---
-
-### PR #464: Sleep Agent Pipeline (Contributor: @laihenyi)
-**Status:** 🔴 Too large for effective review
-
-| Metric | Value |
-|--------|-------|
-| Additions | 15,430 |
-| Deletions | 469 |
-| Files | 73 |
-| Wait time | 37+ days |
-| Risk | High |
-
-**What it does:**
- Sleep Agent Pipeline with memory tiering
- Supersession detection
- Session Statistics API (`/api/session/:id/stats`)
- StatusLine + PreCompact hooks
- Context Generator improvements
- Self-healing CI workflow
-
-**Concerns:**
-| Issue | Details |
-|-------|---------|
-| 🔴 Size | 15K+ lines is too large for effective review |
-| 🔴 SupersessionDetector | Single file with 1,282 additions |
-| 🟡 No tests visible | Test plan checkboxes unchecked |
-| 🟡 Self-healing CI | Auto-fix workflow could cause infinite commit loops |
-| 🟡 Serena config | Adds `.serena/` tooling |
-
-**Recommendation:**
-1. **Option A:** Request contributor split into 4-5 smaller PRs
-2. **Option B:** Allocate dedicated review time (several hours)
-3. **Option C:** Cherry-pick specific features (hooks, stats API)
-
-**Note:** Contributor has been waiting 37+ days. Deserves response either way.
-
---
-
-## Shipping Strategy
-
-### Phase 1: Quick Wins (This Week)
-1. **Merge #856** — Ready now, fixes real user issue
-2. **Rebase #700** — Has approval, Windows fix needed
-3. **Rebase #657** — Useful CLI commands
-
-### Phase 2: Architecture (Careful Review)
-4. **Review #722** — High impact, conflicts with #700 approach?
-   - Both PRs eliminate spawning but in different ways
-   - May need to pick one approach
-
-### Phase 3: Contributor PR
-5. **Respond to #464** — Options:
-   - Ask for split
-   - Schedule dedicated review
-   - Cherry-pick subset
-
-### Phase 4: Investigation
-6. **Manual review #863** — Ragtime email feature
-
---
-
-## Conflict Resolution Order
-
-Since multiple PRs have conflicts, suggested rebase order:
-
-1. **#856** (merge first — no conflicts)
-2. **#700** (rebase onto main after #856)
-3. **#657** (rebase onto main after #700)
-4. **#722** (rebase last — may conflict with #700 architecturally)
-
---
-
-## Summary
-
-| Ready | Conflicts | Needs Work |
-|-------|-----------|------------|
-| 1 PR (#856) | 3 PRs (#700, #722, #657) | 2 PRs (#464, #863) |
-
-**Immediate action:** Merge #856, then rebase the conflict PRs in order.
@@ -1,239 +0,0 @@
-# Session ID Architecture
-
-## Overview
-
-Claude-mem uses **two distinct session IDs** to track conversations and memory:
-
-1. **`contentSessionId`** - The user's Claude Code conversation session ID
-2. **`memorySessionId`** - The SDK agent's internal session ID for resume functionality
-
-## Critical Architecture
-
-### Initialization Flow
-
-```
-┌─────────────────────────────────────────────────────────────┐
-│ 1. Hook creates session                                     │
-│    createSDKSession(contentSessionId, project, prompt)      │
-│                                                              │
-│    Database state:                                          │
-│    ├─ content_session_id: "user-session-123"               │
-│    └─ memory_session_id: NULL (not yet captured)           │
-└─────────────────────────────────────────────────────────────┘
-                           ↓
-┌─────────────────────────────────────────────────────────────┐
-│ 2. SDKAgent starts, checks hasRealMemorySessionId           │
-│    const hasReal = memorySessionId !== null                 │
-│    → FALSE (it's NULL)                                      │
-│    → Resume NOT used (fresh SDK session)                    │
-└─────────────────────────────────────────────────────────────┘
-                           ↓
-┌─────────────────────────────────────────────────────────────┐
-│ 3. First SDK message arrives with session_id                │
-│    updateMemorySessionId(sessionDbId, "sdk-gen-abc123")     │
-│                                                              │
-│    Database state:                                          │
-│    ├─ content_session_id: "user-session-123"               │
-│    └─ memory_session_id: "sdk-gen-abc123" (real!)          │
-└─────────────────────────────────────────────────────────────┘
-                           ↓
-┌─────────────────────────────────────────────────────────────┐
-│ 4. Subsequent prompts use resume                            │
-│    const hasReal = memorySessionId !== null                 │
-│    → TRUE (it's not NULL)                                   │
-│    → Resume parameter: { resume: "sdk-gen-abc123" }         │
-└─────────────────────────────────────────────────────────────┘
-```
-
-### Observation Storage
-
-**CRITICAL**: Observations are stored with `contentSessionId`, NOT the captured SDK `memorySessionId`.
-
-```typescript
-// SDKAgent.ts line 332-333
-this.dbManager.getSessionStore().storeObservation(
-  session.contentSessionId,  // ← contentSessionId, not memorySessionId!
-  session.project,
-  obs,
-  // ...
-);
-```
-
-Even though the parameter is named `memorySessionId`, it receives `contentSessionId`. This means:
-
- Database column: `observations.memory_session_id`
- Stored value: `contentSessionId` (the user's session ID)
- Foreign key: References `sdk_sessions.memory_session_id`
-
-The observations are linked to the session via `contentSessionId`, which remains constant throughout the session lifecycle.
-
-## Key Invariants
-
-### 1. NULL-Based Detection
-
-```typescript
-const hasRealMemorySessionId = session.memorySessionId !== null;
-```
-
- When `memorySessionId === null` → Not yet captured
- When `memorySessionId !== null` → Real SDK session captured
-
-### 2. Resume Safety
-
-**NEVER** use `contentSessionId` for resume:
-
-```typescript
-// ❌ FORBIDDEN - Would resume user's session instead of memory session!
-query({ resume: contentSessionId })
-
-// ✅ CORRECT - Only resume when we have real memory session ID
-query({
-  ...(hasRealMemorySessionId && { resume: memorySessionId })
-})
-```
-
-### 3. Session Isolation
-
- Each `contentSessionId` maps to exactly one database session
- Each database session has one `memorySessionId` (initially NULL, then captured)
- Observations from different content sessions must NEVER mix
-
-### 4. Foreign Key Integrity
-
- Observations reference `sdk_sessions.memory_session_id`
- Initially, `sdk_sessions.memory_session_id` is NULL (no observations can be stored yet)
- When SDK session ID is captured, `sdk_sessions.memory_session_id` is set to the real value
- Observations are stored using `contentSessionId` and remain retrievable via `contentSessionId`
-
-## Testing Strategy
-
-The test suite validates all critical invariants:
-
-### Test File
-
-`tests/session_id_usage_validation.test.ts`
-
-### Test Categories
-
-1. **NULL-Based Detection** - Validates `hasRealMemorySessionId` logic
-2. **Observation Storage** - Confirms observations use `contentSessionId`
-3. **Resume Safety** - Prevents `contentSessionId` from being used for resume
-4. **Cross-Contamination Prevention** - Ensures session isolation
-5. **Foreign Key Integrity** - Validates cascade behavior
-6. **Session Lifecycle** - Tests create → capture → resume flow
-7. **Edge Cases** - Handles NULL, duplicate IDs, etc.
-
-### Running Tests
-
-```bash
-# Run all session ID tests
-bun test tests/session_id_usage_validation.test.ts
-
-# Run all tests
-bun test
-
-# Run with verbose output
-bun test --verbose
-```
-
-## Common Pitfalls
-
-### ❌ Using memorySessionId for observations
-
-```typescript
-// WRONG - Don't use the captured SDK session ID
-storeObservation(session.memorySessionId, ...)
-```
-
-### ❌ Resuming without checking for NULL
-
-```typescript
-// WRONG - memorySessionId could be NULL!
-if (session.memorySessionId) {
-  query({ resume: session.memorySessionId })
-}
-```
-
-### ❌ Assuming memorySessionId is always set
-
-```typescript
-// WRONG - Can be NULL before SDK session is captured
-const resumeId = session.memorySessionId
-```
-
-## Correct Usage Patterns
-
-### ✅ Storing observations
-
-```typescript
-// Always use contentSessionId
-storeObservation(session.contentSessionId, project, obs, ...)
-```
-
-### ✅ Checking for real memory session ID
-
-```typescript
-const hasRealMemorySessionId = session.memorySessionId !== null;
-```
-
-### ✅ Using resume parameter
-
-```typescript
-query({
-  prompt: messageGenerator,
-  options: {
-    ...(hasRealMemorySessionId && { resume: session.memorySessionId }),
-    // ... other options
-  }
-})
-```
-
-## Debugging Tips
-
-### Check session state
-
-```sql
-- See both session IDs
-SELECT
-  id,
-  content_session_id,
-  memory_session_id,
-  CASE
-    WHEN memory_session_id IS NULL THEN 'NOT_CAPTURED'
-    ELSE 'CAPTURED'
-  END as state
-FROM sdk_sessions
-WHERE content_session_id = 'your-session-id';
-```
-
-### Find orphaned observations
-
-```sql
-- Should return 0 rows if FK integrity is maintained
-SELECT o.*
-FROM observations o
-LEFT JOIN sdk_sessions s ON o.memory_session_id = s.memory_session_id
-WHERE s.id IS NULL;
-```
-
-### Verify observation linkage
-
-```sql
-- See which observations belong to a session
-SELECT
-  o.id,
-  o.title,
-  o.memory_session_id,
-  s.content_session_id,
-  s.memory_session_id as session_memory_id
-FROM observations o
-JOIN sdk_sessions s ON o.memory_session_id = s.memory_session_id
-WHERE s.content_session_id = 'your-session-id';
-```
-
-## References
-
- **Implementation**: `src/services/worker/SDKAgent.ts` (lines 72-94)
- **Database Schema**: `src/services/sqlite/SessionStore.ts` (line 95-104)
- **Tests**: `tests/session_id_usage_validation.test.ts`
- **Related Tests**: `tests/session_id_refactor.test.ts`
@@ -1,79 +0,0 @@
-# Version Consistency Fix (Issue #XXX)
-
-## Problem
-Version mismatch between plugin and worker caused infinite restart loop:
- Plugin version: 9.0.0 (from plugin/.claude-plugin/plugin.json)
- Worker binary version: 8.5.9 (hardcoded in bundled worker-service.cjs)
-
-This triggered the auto-restart mechanism on every hook call, which killed the SDK generator before it could complete the Claude API call to generate observations. Result: 0 observations were ever saved to the database despite hooks firing successfully.
-
-## Root Cause
-The `plugin/package.json` file had version `8.5.10` instead of `9.0.0`. When the project was last built, the build script correctly injected the version from root `package.json` into the bundled worker service. However, the `plugin/package.json` was manually created/edited and fell out of sync.
-
-At runtime:
-1. Worker service reads version from `~/.claude/plugins/marketplaces/thedotmack/package.json` → gets `8.5.10`
-2. Running worker returns built-in version via `/api/version` → returns `8.5.9` (from old build)
-3. Version check in `worker-service.ts` start command detects mismatch
-4. Auto-restart triggered on every hook call
-5. Observations never saved
-
-## Solution
-1. Updated `plugin/package.json` from version `8.5.10` to `9.0.0`
-2. Rebuilt all hooks and worker service to inject correct version (`9.0.0`) into bundled artifacts
-3. Added comprehensive test suite to prevent future version mismatches
-
-## Verification
-All versions now match:
-```
-Root package.json:       9.0.0 ✓
-plugin/package.json:     9.0.0 ✓
-plugin.json:             9.0.0 ✓
-marketplace.json:        9.0.0 ✓
-worker-service.cjs:      9.0.0 ✓
-```
-
-## Prevention
-To prevent this issue in the future:
-
-1. **Automated Build Process**: The `scripts/build-hooks.js` now regenerates `plugin/package.json` automatically with the correct version from root `package.json`
-
-2. **Version Consistency Tests**: Added `tests/infrastructure/version-consistency.test.ts` to verify all version sources match
-
-3. **Version Management Best Practices**:
-   - NEVER manually edit `plugin/package.json` - it's auto-generated during build
-   - Always update version in root `package.json` only
-   - Run `npm run build` after version changes
-   - The build script will sync the version to all necessary locations
-
-## Files Changed
- `plugin/package.json` - Updated version from 8.5.10 to 9.0.0
- `plugin/scripts/worker-service.cjs` - Rebuilt with version 9.0.0 injected
- `plugin/scripts/mcp-server.cjs` - Rebuilt with version 9.0.0 injected
- `plugin/scripts/*.js` (hooks) - Rebuilt with version 9.0.0 injected
- `tests/infrastructure/version-consistency.test.ts` - New test suite
-
-## Testing
-Run the version consistency test:
-```bash
-npm run test:infra
-```
-
-Or manually verify:
-```bash
-node -e "
-const fs = require('fs');
-const rootPkg = JSON.parse(fs.readFileSync('package.json', 'utf-8'));
-const pluginPkg = JSON.parse(fs.readFileSync('plugin/package.json', 'utf-8'));
-const workerContent = fs.readFileSync('plugin/scripts/worker-service.cjs', 'utf-8');
-const workerMatch = workerContent.match(/Bre=\"([0-9.]+)\"/);
-console.log('Root:', rootPkg.version);
-console.log('Plugin:', pluginPkg.version);
-console.log('Worker:', workerMatch ? workerMatch[1] : 'NOT_FOUND');
-"
-```
-
-## Related Code Locations
- **Version Injection**: `scripts/build-hooks.js` line 43-45, 105, 130, 155, 178
- **Version Check**: `src/services/infrastructure/HealthMonitor.ts` line 133-143
- **Auto-Restart Logic**: `src/services/worker-service.ts` line 627-645
- **Runtime Version Read**: `src/shared/worker-utils.ts` line 73-76, 82-91
@@ -1,48 +0,0 @@
-# Error Handling Anti-Pattern Cleanup Plan
-
-**Total: 132 anti-patterns to fix**
-
-Run detector: `bun run scripts/anti-pattern-test/detect-error-handling-antipatterns.ts`
-
-## Progress Tracker
-
- [ ] worker-service.ts (36 issues)
- [ ] SearchManager.ts (28 issues)
- [ ] SessionStore.ts (18 issues)
- [ ] import-xml-observations.ts (7 issues)
- [ ] ChromaSync.ts (6 issues)
- [ ] BranchManager.ts (5 issues)
- [ ] mcp-server.ts (5 issues)
- [ ] logger.ts (3 issues)
- [ ] useContextPreview.ts (3 issues)
- [ ] SessionRoutes.ts (3 issues)
- [ ] ModeManager.ts (3 issues)
- [ ] context-generator.ts (3 issues)
- [ ] useTheme.ts (2 issues)
- [ ] useSSE.ts (2 issues)
- [ ] usePagination.ts (2 issues)
- [ ] SessionManager.ts (2 issues)
- [ ] prompts.ts (2 issues)
- [ ] useStats.ts (1 issue)
- [ ] useSettings.ts (1 issue)
- [ ] timeline-formatting.ts (1 issue)
- [ ] paths.ts (1 issue)
- [ ] SettingsDefaultsManager.ts (1 issue)
- [ ] SettingsRoutes.ts (1 issue)
- [ ] BaseRouteHandler.ts (1 issue)
- [ ] SettingsManager.ts (1 issue)
- [ ] SDKAgent.ts (1 issue)
- [ ] PaginationHelper.ts (1 issue)
- [ ] OpenRouterAgent.ts (1 issue)
- [ ] GeminiAgent.ts (1 issue)
- [ ] SessionQueueProcessor.ts (1 issue)
-
-## Final Verification
-
- [ ] Run detector and confirm 0 issues (132 approved overrides remain)
- [ ] All tests pass
- [ ] Commit changes
-
-## Notes
-
-All severity designators removed from detector - every anti-pattern is treated as critical.
@@ -1,140 +0,0 @@
-# claude-mem Architecture Overview
-
-## System Layers
-
-```text
-+-----------------------------------------------------------+
-|  Claude Code (host)                                       |
-|  +-- Hook System (5 events)                               |
-|  +-- MCP Client (search tools)                            |
-+-----------------------------------------------------------+
-|  CLI Layer (Bun)                                          |
-|  +-- bun-runner.js (Node->Bun bridge)                     |
-|  +-- hook-command.ts (orchestrator)                        |
-|  +-- handlers/ (context, session-init, observation,        |
-|                 summarize, session-complete)               |
-+-----------------------------------------------------------+
-|  Worker Daemon (Express, port 37777)                      |
-|  +-- SessionManager (session lifecycle)                   |
-|  +-- SDKAgent (Claude Agent SDK)                          |
-|  +-- SearchManager (search orchestration)                 |
-|  +-- ProcessRegistry (subprocess management)              |
-|  +-- ChromaSync (embedding synchronization)               |
-+-----------------------------------------------------------+
-|  Storage Layer                                            |
-|  +-- SQLite (claude-mem.db) -- structured data            |
-|  +-- ChromaDB (chroma.sqlite3) -- vector embeddings       |
-|  +-- MCP Server (interface for Claude Code)               |
-+-----------------------------------------------------------+
-```
-
-## Hook Lifecycle
-
-| Event | Handler | What it does | Timeout |
-|-------|---------|-------------|---------|
-| Setup | setup.sh | Install system dependencies | 300s |
-| SessionStart | smart-install.js + context | Install deps + start worker + inject context | 60s |
-| UserPromptSubmit | session-init | Register session + start SDK agent + semantic injection | 60s |
-| PostToolUse | observation | Capture tool usage -> enqueue in worker | 120s |
-| Summary | summarize | Request session summary from SDK agent | 120s |
-| SessionEnd | session-complete | End session + drain pending messages | 30s |
-
-## Data Flow
-
-```text
-User prompt -> session-init -> /api/sessions/init + /api/context/semantic
-  |
-Tool use -> observation -> /api/sessions/observations
-  |                              |
-  |                    PendingMessageStore.enqueue()
-  |                              |
-  |                    SDKAgent.startSession()
-  |                              |
-  |                    Claude Agent SDK -> ResponseProcessor
-  |                              |
-  |                    +-- storeObservations() -> SQLite
-  |                    +-- chromaSync.sync() -> ChromaDB
-  |                    +-- broadcastObservation() -> SSE/UI
-  |
-Stop -> summarize -> /api/sessions/summarize
-     -> session-complete -> /api/sessions/complete + drain
-```
-
-## Key Patterns
-
-### CLAIM-CONFIRM (PendingMessageStore)
-
-```text
-enqueue()           -> INSERT status='pending'
-claimNextMessage()  -> UPDATE status='processing' (atomic)
-confirmProcessed()  -> DELETE (success)
-markFailed()        -> UPDATE status='failed' (retry < 3)
-
-Self-healing: messages in 'processing' for >60s reset to 'pending'
-```
-
-### Circuit-Breaker (SessionRoutes)
-
-```text
-Generator crash -> retry 1 (1s) -> retry 2 (2s) -> retry 3 (4s)
-  -> consecutiveRestarts > 3 -> CIRCUIT-BREAKER
-  -> markAllSessionMessagesAbandoned(sessionDbId)
-  -> Stop. No infinite loop.
-```
-
-Counter resets to 0 when generator completes work naturally.
-
-### Graceful Degradation (hook-command.ts)
-
-```text
-Transport errors (ECONNREFUSED, timeout, 5xx) -> exit 0 (never block Claude Code)
-Client bugs (4xx, TypeError, ReferenceError)  -> exit 2 (blocking, needs fix)
-```
-
-The worker being unavailable NEVER blocks the user's Claude Code session.
-
-### Deduplication (observations)
-
-```text
-SHA256(memory_session_id + title + narrative)[:16] -> content_hash (16 hex chars)
-If hash exists within 30s window -> return existing ID (no insert)
-```
-
-### Two Types of Session ID
-
- `contentSessionId` — from Claude Code, invariant during the session
- `memorySessionId` — from SDK Agent, changes on each worker restart
-
-The conversion between them is handled by SessionStore and is critical for FK constraints.
-
-## Storage
-
-### SQLite (claude-mem.db)
-
-| Table | Key fields | Purpose |
-|-------|-----------|---------|
-| sdk_sessions | content_session_id, memory_session_id, status | Session lifecycle |
-| observations | memory_session_id, type, title, narrative, content_hash | Tool usage observations |
-| session_summaries | memory_session_id, request, learned, completed | Session summaries |
-| user_prompts | content_session_id, prompt_text | User prompt history |
-| pending_messages | session_db_id, status, message_type | CLAIM-CONFIRM queue |
-| observation_feedback | observation_id, signal_type | Usage tracking |
-
-### ChromaDB (chroma.sqlite3)
-
-Vector embeddings for semantic search. Each observation generates multiple documents:
-
-```text
-obs_{id}_narrative  -> main text
-obs_{id}_fact_0     -> first fact
-obs_{id}_fact_1     -> second fact
-...
-```
-
-Accessed via chroma-mcp (MCP process), communication over stdio.
-
-## Process Management
-
- **ProcessRegistry:** Tracks all Claude SDK subprocesses, manages PID lifecycle
- **Orphan Reaper (5min):** Kills processes with no active session
- **GracefulShutdown:** 7-step shutdown (PID file, children, HTTP server, sessions, MCP, DB, force-kill)
@@ -1,98 +0,0 @@
---
-Title: Bug: SDK Agent fails on Windows when username contains spaces
---
-
-## Bug Report
-
-**Summary:** Claude SDK Agent fails to start on Windows when the user's path contains spaces (e.g., `C:\Users\Anderson Wang\`), causing PostToolUse hooks to hang indefinitely.
-
-**Severity:** High - Core functionality broken
-
-**Affected Platform:** Windows only
-
---
-
-## Symptoms
-
-PostToolUse hook displays `(1/2 done)` indefinitely. Worker logs show:
-
-```
-ERROR [SESSION] Generator failed {provider=claude, error=Claude Code process exited with code 1}
-ERROR [SESSION] Generator exited unexpectedly
-```
-
---
-
-## Root Cause
-
-Two issues in the Windows code path:
-
-1. **`SDKAgent.ts`** - Returns full auto-detected path with spaces:
-   ```
-   C:\Users\Anderson Wang\AppData\Roaming\npm\claude.cmd
-   ```
-
-2. **`ProcessRegistry.ts`** - Node.js `spawn()` cannot directly execute `.cmd` files when the path contains spaces
-
---
-
-## Proposed Fix
-
-### File 1: `src/services/worker/SDKAgent.ts`
-
-On Windows, prefer `claude.cmd` via PATH instead of full auto-detected path:
-
-```typescript
-// On Windows, prefer "claude.cmd" (via PATH) to avoid spawn issues with spaces in paths
-if (process.platform === 'win32') {
-  try {
-    execSync('where claude.cmd', { encoding: 'utf8', windowsHide: true, stdio: ['ignore', 'pipe', 'ignore'] });
-    return 'claude.cmd'; // Let Windows resolve via PATHEXT
-  } catch {
-    // Fall through to generic error
-  }
-}
-```
-
-### File 2: `src/services/worker/ProcessRegistry.ts`
-
-Use `cmd.exe /d /c` wrapper for .cmd files on Windows:
-
-```typescript
-const useCmdWrapper = process.platform === 'win32' && spawnOptions.command.endsWith('.cmd');
-
-if (useCmdWrapper) {
-  child = spawn('cmd.exe', ['/d', '/c', spawnOptions.command, ...spawnOptions.args], {
-    cwd: spawnOptions.cwd,
-    env: spawnOptions.env,
-    stdio: ['pipe', 'pipe', 'pipe'],
-    signal: spawnOptions.signal,
-    windowsHide: true
-  });
-}
-```
-
---
-
-## Why This Works
-
- **PATHEXT Resolution:** Windows searches PATH and tries each extension in PATHEXT automatically
- **cmd.exe wrapper:** Properly handles paths with spaces and argument passing
- **Avoids shell parsing:** Using direct arguments instead of `shell: true` prevents empty string misparsing
-
---
-
-## Testing
-
-Verified on Windows 11 with username containing spaces:
- PostToolUse hook completes successfully
- Observations are stored to database
- No more "process exited with code 1" errors
-
---
-
-## Additional Notes
-
- Maintains backward compatibility with `CLAUDE_CODE_PATH` setting
- No impact on non-Windows platforms
- Related to Issue #733 (credential isolation) - separate fix
@@ -1,128 +0,0 @@
-/**
- * Claude Agent SDK V2 Examples
- *
- * The V2 API provides a session-based interface with separate send()/receive(),
- * ideal for multi-turn conversations. Run with: npx tsx v2-examples.ts
- */
-
-import {
-  unstable_v2_createSession,
-  unstable_v2_resumeSession,
-  unstable_v2_prompt,
-} from '@anthropic-ai/claude-agent-sdk';
-
-async function main() {
-  const example = process.argv[2] || 'basic';
-
-  switch (example) {
-    case 'basic':
-      await basicSession();
-      break;
-    case 'multi-turn':
-      await multiTurn();
-      break;
-    case 'one-shot':
-      await oneShot();
-      break;
-    case 'resume':
-      await sessionResume();
-      break;
-    default:
-      console.log('Usage: npx tsx v2-examples.ts [basic|multi-turn|one-shot|resume]');
-  }
-}
-
-// Basic session with send/receive pattern
-async function basicSession() {
-  console.log('=== Basic Session ===\n');
-
-  await using session = unstable_v2_createSession({ model: 'sonnet' });
-  await session.send('Hello! Introduce yourself in one sentence.');
-
-  for await (const msg of session.receive()) {
-    if (msg.type === 'assistant') {
-      const text = msg.message.content.find((c): c is { type: 'text'; text: string } => c.type === 'text');
-      console.log(`Claude: ${text?.text}`);
-    }
-  }
-}
-
-// Multi-turn conversation - V2's key advantage
-async function multiTurn() {
-  console.log('=== Multi-Turn Conversation ===\n');
-
-  await using session = unstable_v2_createSession({ model: 'sonnet' });
-
-  // Turn 1
-  await session.send('What is 5 + 3? Just the number.');
-  for await (const msg of session.receive()) {
-    if (msg.type === 'assistant') {
-      const text = msg.message.content.find((c): c is { type: 'text'; text: string } => c.type === 'text');
-      console.log(`Turn 1: ${text?.text}`);
-    }
-  }
-
-  // Turn 2 - Claude remembers context
-  await session.send('Multiply that by 2. Just the number.');
-  for await (const msg of session.receive()) {
-    if (msg.type === 'assistant') {
-      const text = msg.message.content.find((c): c is { type: 'text'; text: string } => c.type === 'text');
-      console.log(`Turn 2: ${text?.text}`);
-    }
-  }
-}
-
-// One-shot convenience function
-async function oneShot() {
-  console.log('=== One-Shot Prompt ===\n');
-
-  const result = await unstable_v2_prompt('What is the capital of France? One word.', { model: 'sonnet' });
-
-  if (result.subtype === 'success') {
-    console.log(`Answer: ${result.result}`);
-    console.log(`Cost: $${result.total_cost_usd.toFixed(4)}`);
-  }
-}
-
-// Session resume - persist context across sessions
-async function sessionResume() {
-  console.log('=== Session Resume ===\n');
-
-  let sessionId: string | undefined;
-
-  // First session - establish a memory
-  {
-    await using session = unstable_v2_createSession({ model: 'sonnet' });
-    console.log('[Session 1] Telling Claude my favorite color...');
-    await session.send('My favorite color is blue. Remember this!');
-
-    for await (const msg of session.receive()) {
-      if (msg.type === 'system' && msg.subtype === 'init') {
-        sessionId = msg.session_id;
-        console.log(`[Session 1] ID: ${sessionId}`);
-      }
-      if (msg.type === 'assistant') {
-        const text = msg.message.content.find((c): c is { type: 'text'; text: string } => c.type === 'text');
-        console.log(`[Session 1] Claude: ${text?.text}\n`);
-      }
-    }
-  }
-
-  console.log('--- Session closed. Time passes... ---\n');
-
-  // Resume and verify Claude remembers
-  {
-    await using session = unstable_v2_resumeSession(sessionId!, { model: 'sonnet' });
-    console.log('[Session 2] Resuming and asking Claude...');
-    await session.send('What is my favorite color?');
-
-    for await (const msg of session.receive()) {
-      if (msg.type === 'assistant') {
-        const text = msg.message.content.find((c): c is { type: 'text'; text: string } => c.type === 'text');
-        console.log(`[Session 2] Claude: ${text?.text}`);
-      }
-    }
-  }
-}
-
-main().catch(console.error);
@@ -1,586 +0,0 @@
-# Hooks
-
-Hooks let you observe, control, and extend the agent loop using custom scripts. Hooks are spawned processes that communicate over stdio using JSON in both directions. They run before or after defined stages of the agent loop and can observe, block, or modify behavior.
-
-With hooks, you can:
-
- Run formatters after edits
- Add analytics for events
- Scan for PII or secrets
- Gate risky operations (e.g., SQL writes)
-
-<Tip>
-Looking for ready-to-use integrations? See [Partner Integrations](#partner-integrations) for security, governance, and secrets management solutions from our ecosystem partners.
-</Tip>
-
-## Agent and Tab Support
-
-Hooks work with both **Cursor Agent** (Cmd+K/Agent Chat) and **Cursor Tab** (inline completions), but they use different hook events:
-
-**Agent (Cmd+K/Agent Chat)** uses the standard hooks:
- `beforeShellExecution` / `afterShellExecution` - Control shell commands
- `beforeMCPExecution` / `afterMCPExecution` - Control MCP tool usage
- `beforeReadFile` / `afterFileEdit` - Control file access and edits
- `beforeSubmitPrompt` - Validate prompts before submission
- `stop` - Handle agent completion
- `afterAgentResponse` / `afterAgentThought` - Track agent responses
-
-**Tab (inline completions)** uses specialized hooks:
- `beforeTabFileRead` - Control file access for Tab completions
- `afterTabFileEdit` - Post-process Tab edits
-
-These separate hooks allow different policies for autonomous Tab operations versus user-directed Agent operations.
-
-## Quickstart
-
-Create a `hooks.json` file. You can create it at the project level (`<project>/.cursor/hooks.json`) or in your home directory (`~/.cursor/hooks.json`). Project-level hooks apply only to that specific project, while home directory hooks apply globally.
-
-```json
-{
-  "version": 1,
-  "hooks": {
-    "afterFileEdit": [{ "command": "./hooks/format.sh" }]
-  }
-}
-```
-
-Create your hook script at `~/.cursor/hooks/format.sh`:
-
-```bash
-#!/bin/bash
-# Read input, do something, exit 0
-cat > /dev/null
-exit 0
-```
-
-Make it executable:
-
-```bash
-chmod +x ~/.cursor/hooks/format.sh
-```
-
-Restart Cursor. Your hook now runs after every file edit.
-
-## Examples
-
-<CodeGroup>
-
-```json title="hooks.json"
-{
-  "version": 1,
-  "hooks": {
-    "beforeShellExecution": [
-      {
-        "command": "./hooks/audit.sh"
-      },
-      {
-        "command": "./hooks/block-git.sh"
-      }
-    ],
-    "beforeMCPExecution": [
-      {
-        "command": "./hooks/audit.sh"
-      }
-    ],
-    "afterShellExecution": [
-      {
-        "command": "./hooks/audit.sh"
-      }
-    ],
-    "afterMCPExecution": [
-      {
-        "command": "./hooks/audit.sh"
-      }
-    ],
-    "afterFileEdit": [
-      {
-        "command": "./hooks/audit.sh"
-      }
-    ],
-    "beforeSubmitPrompt": [
-      {
-        "command": "./hooks/audit.sh"
-      }
-    ],
-    "stop": [
-      {
-        "command": "./hooks/audit.sh"
-      }
-    ],
-    "beforeTabFileRead": [
-      {
-        "command": "./hooks/redact-secrets-tab.sh"
-      }
-    ],
-    "afterTabFileEdit": [
-      {
-        "command": "./hooks/format-tab.sh"
-      }
-    ]
-  }
-}
-```
-
-```sh title="audit.sh"
-#!/bin/bash
-
-# audit.sh - Hook script that writes all JSON input to /tmp/agent-audit.log
-# This script is designed to be called by Cursor's hooks system for auditing purposes
-
-# Read JSON input from stdin
-json_input=$(cat)
-
-# Create timestamp for the log entry
-timestamp=$(date '+%Y-%m-%d %H:%M:%S')
-
-# Create the log directory if it doesn't exist
-mkdir -p "$(dirname /tmp/agent-audit.log)"
-
-# Write the timestamped JSON entry to the audit log
-echo "[$timestamp] $json_input" >> /tmp/agent-audit.log
-
-# Exit successfully
-exit 0
-```
-
-```sh title="block-git.sh"
-#!/bin/bash
-
-# Hook to block git commands and redirect to gh tool usage
-# This hook implements the beforeShellExecution hook from the Cursor Hooks Spec
-
-# Initialize debug logging
-echo "Hook execution started" >> /tmp/hooks.log
-
-# Read JSON input from stdin
-input=$(cat)
-echo "Received input: $input" >> /tmp/hooks.log
-
-# Parse the command from the JSON input
-command=$(echo "$input" | jq -r '.command // empty')
-echo "Parsed command: '$command'" >> /tmp/hooks.log
-
-# Check if the command contains 'git' or 'gh'
-if [[ "$command" =~ git[[:space:]] ]] || [[ "$command" == "git" ]]; then
-    echo "Git command detected - blocking: '$command'" >> /tmp/hooks.log
-    # Block the git command and provide guidance to use gh tool instead
-    cat << EOF
-{
-  "continue": true,
-  "permission": "deny",
-  "user_message": "Git command blocked. Please use the GitHub CLI (gh) tool instead.",
-  "agent_message": "The git command '$command' has been blocked by a hook. Instead of using raw git commands, please use the 'gh' tool which provides better integration with GitHub and follows best practices. For example:\n- Instead of 'git clone', use 'gh repo clone'\n- Instead of 'git push', use 'gh repo sync' or the appropriate gh command\n- For other git operations, check if there's an equivalent gh command or use the GitHub web interface\n\nThis helps maintain consistency and leverages GitHub's enhanced tooling."
-}
-EOF
-elif [[ "$command" =~ gh[[:space:]] ]] || [[ "$command" == "gh" ]]; then
-    echo "GitHub CLI command detected - asking for permission: '$command'" >> /tmp/hooks.log
-    # Ask for permission for gh commands
-    cat << EOF
-{
-  "continue": true,
-  "permission": "ask",
-  "user_message": "GitHub CLI command requires permission: $command",
-  "agent_message": "The command '$command' uses the GitHub CLI (gh) which can interact with your GitHub repositories and account. Please review and approve this command if you want to proceed."
-}
-EOF
-else
-    echo "Non-git/non-gh command detected - allowing: '$command'" >> /tmp/hooks.log
-    # Allow non-git/non-gh commands
-    cat << EOF
-{
-  "continue": true,
-  "permission": "allow"
-}
-EOF
-fi
-```
-
-</CodeGroup>
-
-## Partner Integrations
-
-We partner with ecosystem vendors who have built hooks support with Cursor. These integrations cover security scanning, governance, secrets management, and more.
-
-### MCP governance and visibility
-
-| Partner | Description |
-|---------|-------------|
-| [MintMCP](https://www.mintmcp.com/blog/mcp-governance-cursor-hooks) | Build a complete inventory of MCP servers, monitor tool usage patterns, and scan responses for sensitive data before it reaches the AI model. |
-| [Oasis Security](https://www.oasis.security/blog/cursor-oasis-governing-agentic-access) | Enforce least-privilege policies on AI agent actions and maintain full audit trails across enterprise systems. |
-| [Runlayer](https://www.runlayer.com/blog/cursor-hooks) | Wrap MCP tools and integrate with their MCP broker for centralized control and visibility over agent-to-tool interactions. |
-
-### Code security and best practices
-
-| Partner | Description |
-|---------|-------------|
-| [Corridor](https://corridor.dev/blog/corridor-cursor-hooks/) | Get real-time feedback on code implementation and security design decisions as code is being written. |
-| [Semgrep](https://semgrep.dev/blog/2025/cursor-hooks-mcp-server) | Automatically scan AI-generated code for vulnerabilities with real-time feedback to regenerate code until security issues are resolved. |
-
-### Dependency security
-
-| Partner | Description |
-|---------|-------------|
-| [Endor Labs](https://www.endorlabs.com/learn/bringing-malware-detection-into-ai-coding-workflows-with-cursor-hooks) | Intercept package installations and scan for malicious dependencies, preventing supply chain attacks before they enter your codebase. |
-
-### Agent security and safety
-
-| Partner | Description |
-|---------|-------------|
-| [Snyk](https://snyk.io/blog/evo-agent-guard-cursor-integration/) | Review agent actions in real-time with Evo Agent Guard, detecting and preventing issues like prompt injection and dangerous tool calls. |
-
-### Secrets management
-
-| Partner | Description |
-|---------|-------------|
-| [1Password](https://marketplace.1password.com/integration/cursor-hooks) | Validate that environment files from 1Password Environments are properly mounted before shell commands execute, enabling just-in-time secrets access without writing credentials to disk. |
-
-For more details about our hooks partners, see the [Hooks for security and platform teams](/blog/hooks-partners) blog post.
-
-## Configuration
-
-Define hooks in a `hooks.json` file. Configuration can exist at multiple levels; higher-priority sources override lower ones:
-
-```sh
-~/.cursor/
-├── hooks.json
-└── hooks/
-    ├── audit.sh
-    └── block-git.sh
-```
-
- **Global** (Enterprise-managed):
-  - macOS: `/Library/Application Support/Cursor/hooks.json`
-  - Linux/WSL: `/etc/cursor/hooks.json`
-  - Windows: `C:\\ProgramData\\Cursor\\hooks.json`
- **Project Directory** (Project-specific):
-  - `<project-root>/.cursor/hooks.json`
-  - Project hooks run in any trusted workspace and are checked into version control with your project
- **Home Directory** (User-specific):
-  - `~/.cursor/hooks.json`
-
-Priority order (highest to lowest): Enterprise → Project → User
-
-The `hooks` object maps hook names to arrays of hook definitions. Each definition currently supports a `command` property that can be a shell string, an absolute path, or a path relative to the `hooks.json` file.
-
-### Configuration file
-
-```json
-{
-  "version": 1,
-  "hooks": {
-    "beforeShellExecution": [{ "command": "./script.sh" }],
-    "afterShellExecution": [{ "command": "./script.sh" }],
-    "afterMCPExecution": [{ "command": "./script.sh" }],
-    "afterFileEdit": [{ "command": "./format.sh" }],
-    "beforeTabFileRead": [{ "command": "./redact-secrets-tab.sh" }],
-    "afterTabFileEdit": [{ "command": "./format-tab.sh" }]
-  }
-}
-```
-
-The Agent hooks (`beforeShellExecution`, `afterShellExecution`, `beforeMCPExecution`, `afterMCPExecution`, `beforeReadFile`, `afterFileEdit`, `beforeSubmitPrompt`, `stop`, `afterAgentResponse`, `afterAgentThought`) apply to Cmd+K and Agent Chat operations. The Tab hooks (`beforeTabFileRead`, `afterTabFileEdit`) apply specifically to inline Tab completions.
-
-## Team Distribution
-
-Hooks can be distributed to team members using project hooks (via version control), MDM tools, or Cursor's cloud distribution system.
-
-### Project Hooks (Version Control)
-
-Project hooks are the simplest way to share hooks with your team. Place a `hooks.json` file at `<project-root>/.cursor/hooks.json` and commit it to your repository. When team members open the project in a trusted workspace, Cursor automatically loads and runs the project hooks.
-
-Project hooks:
- Are stored in version control alongside your code
- Automatically load for all team members in trusted workspaces
- Can be project-specific (e.g., enforce formatting standards for a particular codebase)
- Require the workspace to be trusted to run (for security)
-
-### MDM Distribution
-
-Distribute hooks across your organization using Mobile Device Management (MDM) tools. Place the `hooks.json` file and hook scripts in the target directories on each machine.
-
-**User home directory** (per-user distribution):
- `~/.cursor/hooks.json`
- `~/.cursor/hooks/` (for hook scripts)
-
-**Global directories** (system-wide distribution):
- macOS: `/Library/Application Support/Cursor/hooks.json`
- Linux/WSL: `/etc/cursor/hooks.json`
- Windows: `C:\\ProgramData\\Cursor\\hooks.json`
-
-Note: MDM-based distribution is fully managed by your organization. Cursor does not deploy or manage files through your MDM solution. Ensure your internal IT or security team handles configuration, deployment, and updates in accordance with your organization's policies.
-
-### Cloud Distribution (Enterprise Only)
-
-Enterprise teams can use Cursor's native cloud distribution to automatically sync hooks to all team members. Configure hooks in the [web dashboard](https://cursor.com/dashboard?tab=team-content&section=hooks). Cursor automatically delivers configured hooks to all client machines when team members log in.
-
-Cloud distribution provides:
-
- Automatic synchronization to all team members (every thirty minutes)
- Operating system targeting for platform-specific hooks
- Centralized management through the dashboard
-
-Enterprise administrators can create, edit, and manage team hooks from the dashboard without requiring access to individual machines.
-
-## Reference
-
-### Common schema
-
-#### Input (all hooks)
-
-All hooks receive a base set of fields in addition to their hook-specific fields:
-
-```json
-{
-  "conversation_id": "string",
-  "generation_id": "string",
-  "model": "string",
-  "hook_event_name": "string",
-  "cursor_version": "string",
-  "workspace_roots": ["<path>"],
-  "user_email": "string | null"
-}
-```
-
-| Field | Type | Description |
-|-------|------|-------------|
-| `conversation_id` | string | Stable ID of the conversation across many turns |
-| `generation_id` | string | The current generation that changes with every user message |
-| `model` | string | The model configured for the composer that triggered the hook |
-| `hook_event_name` | string | Which hook is being run |
-| `cursor_version` | string | Cursor application version (e.g. "1.7.2") |
-| `workspace_roots` | string[] | The list of root folders in the workspace (normally just one, but multiroot workspaces can have multiple) |
-| `user_email` | string \| null | Email address of the authenticated user, if available |
-
-### Hook events
-
-#### beforeShellExecution / beforeMCPExecution
-
-Called before any shell command or MCP tool is executed. Return a permission decision.
-
-```json
-// beforeShellExecution input
-{
-  "command": "<full terminal command>",
-  "cwd": "<current working directory>"
-}
-
-// beforeMCPExecution input
-{
-  "tool_name": "<tool name>",
-  "tool_input": "<json params>"
-}
-// Plus either:
-{ "url": "<server url>" }
-// Or:
-{ "command": "<command string>" }
-
-// Output
-{
-  "permission": "allow" | "deny" | "ask",
-  "user_message": "<message shown in client>",
-  "agent_message": "<message sent to agent>"
-}
-```
-
-#### afterShellExecution
-
-Fires after a shell command executes; useful for auditing or collecting metrics from command output.
-
-```json
-// Input
-{
-  "command": "<full terminal command>",
-  "output": "<full terminal output>",
-  "duration": 1234
-}
-```
-
-| Field | Type | Description |
-|-------|------|-------------|
-| `command` | string | The full terminal command that was executed |
-| `output` | string | Full output captured from the terminal |
-| `duration` | number | Duration in milliseconds spent executing the shell command (excludes approval wait time) |
-
-#### afterMCPExecution
-
-Fires after an MCP tool executes; includes the tool's input parameters and full JSON result.
-
-```json
-// Input
-{
-  "tool_name": "<tool name>",
-  "tool_input": "<json params>",
-  "result_json": "<tool result json>",
-  "duration": 1234
-}
-```
-
-| Field | Type | Description |
-|-------|------|-------------|
-| `tool_name` | string | Name of the MCP tool that was executed |
-| `tool_input` | string | JSON params string passed to the tool |
-| `result_json` | string | JSON string of the tool response |
-| `duration` | number | Duration in milliseconds spent executing the MCP tool (excludes approval wait time) |
-
-#### afterFileEdit
-
-Fires after the Agent edits a file; useful for formatters or accounting of agent-written code.
-
-```json
-// Input
-{
-  "file_path": "<absolute path>",
-  "edits": [{ "old_string": "<search>", "new_string": "<replace>" }]
-}
-```
-
-#### beforeTabFileRead
-
-Called before Tab (inline completions) reads a file. Enable redaction or access control before Tab accesses file contents.
-
-**Key differences from `beforeReadFile`:**
- Only triggered by Tab, not Agent
- Does not include `attachments` field (Tab doesn't use prompt attachments)
- Useful for applying different policies to autonomous Tab operations
-
-```json
-// Input
-{
-  "file_path": "<absolute path>",
-  "content": "<file contents>"
-}
-
-// Output
-{
-  "permission": "allow" | "deny"
-}
-```
-
-#### afterTabFileEdit
-
-Called after Tab (inline completions) edits a file. Useful for formatters or auditing of Tab-written code.
-
-**Key differences from `afterFileEdit`:**
- Only triggered by Tab, not Agent
- Includes detailed edit information: `range`, `old_line`, and `new_line` for precise edit tracking
- Useful for fine-grained formatting or analysis of Tab edits
-
-```json
-// Input
-{
-  "file_path": "<absolute path>",
-  "edits": [
-    {
-      "old_string": "<search>",
-      "new_string": "<replace>",
-      "range": {
-        "start_line_number": 10,
-        "start_column": 5,
-        "end_line_number": 10,
-        "end_column": 20
-      },
-      "old_line": "<line before edit>",
-      "new_line": "<line after edit>"
-    }
-  ]
-}
-
-// Output
-{
-  // No output fields currently supported
-}
-```
-
-#### beforeSubmitPrompt
-
-Called right after user hits send but before backend request. Can prevent submission.
-
-```json
-// Input
-{
-  "prompt": "<user prompt text>",
-  "attachments": [
-    {
-      "type": "file" | "rule",
-      "filePath": "<absolute path>"
-    }
-  ]
-}
-
-// Output
-{
-  "continue": true | false,
-  "user_message": "<message shown to user when blocked>"
-}
-```
-
-| Output Field | Type | Description |
-|--------------|------|-------------|
-| `continue` | boolean | Whether to allow the prompt submission to proceed |
-| `user_message` | string (optional) | Message shown to the user when the prompt is blocked |
-
-#### afterAgentResponse
-
-Called after the agent has completed an assistant message.
-
-```json
-// Input
-{
-  "text": "<assistant final text>"
-}
-```
-
-#### afterAgentThought
-
-Called after the agent completes a thinking block. Useful for observing the agent's reasoning process.
-
-```json
-// Input
-{
-  "text": "<fully aggregated thinking text>",
-  "duration_ms": 5000
-}
-
-// Output
-{
-  // No output fields currently supported
-}
-```
-
-| Field | Type | Description |
-|-------|------|-------------|
-| `text` | string | Fully aggregated thinking text for the completed block |
-| `duration_ms` | number (optional) | Duration in milliseconds for the thinking block |
-
-#### stop
-
-Called when the agent loop ends. Can optionally auto-submit a follow-up user message to keep iterating.
-
-```json
-// Input
-{
-  "status": "completed" | "aborted" | "error",
-  "loop_count": 0
-}
-```
-
-```json
-// Output
-{
-  "followup_message": "<message text>"
-}
-```
-
- The optional `followup_message` is a string. When provided and non-empty, Cursor will automatically submit it as the next user message. This enables loop-style flows (e.g., iterate until a goal is met).
- The `loop_count` field indicates how many times the stop hook has already triggered an automatic follow-up for this conversation (starts at 0). To prevent infinite loops, a maximum of 5 auto follow-ups is enforced.
-
-## Troubleshooting
-
-**How to confirm hooks are active**
-
-There is a Hooks tab in Cursor Settings to debug configured and executed hooks, as well as a Hooks output channel to see errors.
-
-**If hooks are not working**
-
- Restart Cursor to ensure the hooks service is running.
- Ensure hook script paths are relative to `hooks.json` when using relative paths.
@@ -1,338 +0,0 @@
-# Get started with Claude Code hooks
-
-> Learn how to customize and extend Claude Code's behavior by registering shell commands
-
-Claude Code hooks are user-defined shell commands that execute at various points
-in Claude Code's lifecycle. Hooks provide deterministic control over Claude
-Code's behavior, ensuring certain actions always happen rather than relying on
-the LLM to choose to run them.
-
-<Tip>
-  For reference documentation on hooks, see [Hooks reference](/en/hooks).
-</Tip>
-
-Example use cases for hooks include:
-
-* **Notifications**: Customize how you get notified when Claude Code is awaiting
-  your input or permission to run something.
-* **Automatic formatting**: Run `prettier` on .ts files, `gofmt` on .go files,
-  etc. after every file edit.
-* **Logging**: Track and count all executed commands for compliance or
-  debugging.
-* **Feedback**: Provide automated feedback when Claude Code produces code that
-  does not follow your codebase conventions.
-* **Custom permissions**: Block modifications to production files or sensitive
-  directories.
-
-By encoding these rules as hooks rather than prompting instructions, you turn
-suggestions into app-level code that executes every time it is expected to run.
-
-<Warning>
-  You must consider the security implication of hooks as you add them, because hooks run automatically during the agent loop with your current environment's credentials.
-  For example, malicious hooks code can exfiltrate your data. Always review your hooks implementation before registering them.
-
-  For full security best practices, see [Security Considerations](/en/hooks#security-considerations) in the hooks reference documentation.
-</Warning>
-
-## Hook Events Overview
-
-Claude Code provides several hook events that run at different points in the
-workflow:
-
-* **PreToolUse**: Runs before tool calls (can block them)
-* **PermissionRequest**: Runs when a permission dialog is shown (can allow or deny)
-* **PostToolUse**: Runs after tool calls complete
-* **UserPromptSubmit**: Runs when the user submits a prompt, before Claude processes it
-* **Notification**: Runs when Claude Code sends notifications
-* **Stop**: Runs when Claude Code finishes responding
-* **SubagentStop**: Runs when subagent tasks complete
-* **PreCompact**: Runs before Claude Code is about to run a compact operation
-* **SessionStart**: Runs when Claude Code starts a new session or resumes an existing session
-* **SessionEnd**: Runs when Claude Code session ends
-
-Each event receives different data and can control Claude's behavior in
-different ways.
-
-## Quickstart
-
-In this quickstart, you'll add a hook that logs the shell commands that Claude
-Code runs.
-
-### Prerequisites
-
-Install `jq` for JSON processing in the command line.
-
-### Step 1: Open hooks configuration
-
-Run the `/hooks` [slash command](/en/slash-commands) and select
-the `PreToolUse` hook event.
-
-`PreToolUse` hooks run before tool calls and can block them while providing
-Claude feedback on what to do differently.
-
-### Step 2: Add a matcher
-
-Select `+ Add new matcher…` to run your hook only on Bash tool calls.
-
-Type `Bash` for the matcher.
-
-<Note>You can use `*` to match all tools.</Note>
-
-### Step 3: Add the hook
-
-Select `+ Add new hook…` and enter this command:
-
-```bash  theme={null}
-jq -r '"\(.tool_input.command) - \(.tool_input.description // "No description")"' >> ~/.claude/bash-command-log.txt
-```
-
-### Step 4: Save your configuration
-
-For storage location, select `User settings` since you're logging to your home
-directory. This hook will then apply to all projects, not just your current
-project.
-
-Then press `Esc` until you return to the REPL. Your hook is now registered.
-
-### Step 5: Verify your hook
-
-Run `/hooks` again or check `~/.claude/settings.json` to see your configuration:
-
-```json  theme={null}
-{
-  "hooks": {
-    "PreToolUse": [
-      {
-        "matcher": "Bash",
-        "hooks": [
-          {
-            "type": "command",
-            "command": "jq -r '\"\\(.tool_input.command) - \\(.tool_input.description // \"No description\")\"' >> ~/.claude/bash-command-log.txt"
-          }
-        ]
-      }
-    ]
-  }
-}
-```
-
-### Step 6: Test your hook
-
-Ask Claude to run a simple command like `ls` and check your log file:
-
-```bash  theme={null}
-cat ~/.claude/bash-command-log.txt
-```
-
-You should see entries like:
-
-```
-ls - Lists files and directories
-```
-
-## More Examples
-
-<Note>
-  For a complete example implementation, see the [bash command validator example](https://github.com/anthropics/claude-code/blob/main/examples/hooks/bash_command_validator_example.py) in our public codebase.
-</Note>
-
-### Code Formatting Hook
-
-Automatically format TypeScript files after editing:
-
-```json  theme={null}
-{
-  "hooks": {
-    "PostToolUse": [
-      {
-        "matcher": "Edit|Write",
-        "hooks": [
-          {
-            "type": "command",
-            "command": "jq -r '.tool_input.file_path' | { read file_path; if echo \"$file_path\" | grep -q '\\.ts$'; then npx prettier --write \"$file_path\"; fi; }"
-          }
-        ]
-      }
-    ]
-  }
-}
-```
-
-### Markdown Formatting Hook
-
-Automatically fix missing language tags and formatting issues in markdown files:
-
-```json  theme={null}
-{
-  "hooks": {
-    "PostToolUse": [
-      {
-        "matcher": "Edit|Write",
-        "hooks": [
-          {
-            "type": "command",
-            "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/markdown_formatter.py"
-          }
-        ]
-      }
-    ]
-  }
-}
-```
-
-Create `.claude/hooks/markdown_formatter.py` with this content:
-
-````python  theme={null}
-#!/usr/bin/env python3
-"""
-Markdown formatter for Claude Code output.
-Fixes missing language tags and spacing issues while preserving code content.
-"""
-import json
-import sys
-import re
-import os
-
-def detect_language(code):
-    """Best-effort language detection from code content."""
-    s = code.strip()
-    
-    # JSON detection
-    if re.search(r'^\s*[{\[]', s):
-        try:
-            json.loads(s)
-            return 'json'
-        except:
-            pass
-    
-    # Python detection
-    if re.search(r'^\s*def\s+\w+\s*\(', s, re.M) or \
-       re.search(r'^\s*(import|from)\s+\w+', s, re.M):
-        return 'python'
-    
-    # JavaScript detection  
-    if re.search(r'\b(function\s+\w+\s*\(|const\s+\w+\s*=)', s) or \
-       re.search(r'=>|console\.(log|error)', s):
-        return 'javascript'
-    
-    # Bash detection
-    if re.search(r'^#!.*\b(bash|sh)\b', s, re.M) or \
-       re.search(r'\b(if|then|fi|for|in|do|done)\b', s):
-        return 'bash'
-    
-    # SQL detection
-    if re.search(r'\b(SELECT|INSERT|UPDATE|DELETE|CREATE)\s+', s, re.I):
-        return 'sql'
-        
-    return 'text'
-
-def format_markdown(content):
-    """Format markdown content with language detection."""
-    # Fix unlabeled code fences
-    def add_lang_to_fence(match):
-        indent, info, body, closing = match.groups()
-        if not info.strip():
-            lang = detect_language(body)
-            return f"{indent}```{lang}\n{body}{closing}\n"
-        return match.group(0)
-    
-    fence_pattern = r'(?ms)^([ \t]{0,3})```([^\n]*)\n(.*?)(\n\1```)\s*$'
-    content = re.sub(fence_pattern, add_lang_to_fence, content)
-    
-    # Fix excessive blank lines (only outside code fences)
-    content = re.sub(r'\n{3,}', '\n\n', content)
-    
-    return content.rstrip() + '\n'
-
-# Main execution
-try:
-    input_data = json.load(sys.stdin)
-    file_path = input_data.get('tool_input', {}).get('file_path', '')
-    
-    if not file_path.endswith(('.md', '.mdx')):
-        sys.exit(0)  # Not a markdown file
-    
-    if os.path.exists(file_path):
-        with open(file_path, 'r', encoding='utf-8') as f:
-            content = f.read()
-        
-        formatted = format_markdown(content)
-        
-        if formatted != content:
-            with open(file_path, 'w', encoding='utf-8') as f:
-                f.write(formatted)
-            print(f"✓ Fixed markdown formatting in {file_path}")
-    
-except Exception as e:
-    print(f"Error formatting markdown: {e}", file=sys.stderr)
-    sys.exit(1)
-````
-
-Make the script executable:
-
-```bash  theme={null}
-chmod +x .claude/hooks/markdown_formatter.py
-```
-
-This hook automatically:
-
-* Detects programming languages in unlabeled code blocks
-* Adds appropriate language tags for syntax highlighting
-* Fixes excessive blank lines while preserving code content
-* Only processes markdown files (`.md`, `.mdx`)
-
-### Custom Notification Hook
-
-Get desktop notifications when Claude needs input:
-
-```json  theme={null}
-{
-  "hooks": {
-    "Notification": [
-      {
-        "matcher": "",
-        "hooks": [
-          {
-            "type": "command",
-            "command": "notify-send 'Claude Code' 'Awaiting your input'"
-          }
-        ]
-      }
-    ]
-  }
-}
-```
-
-### File Protection Hook
-
-Block edits to sensitive files:
-
-```json  theme={null}
-{
-  "hooks": {
-    "PreToolUse": [
-      {
-        "matcher": "Edit|Write",
-        "hooks": [
-          {
-            "type": "command",
-            "command": "python3 -c \"import json, sys; data=json.load(sys.stdin); path=data.get('tool_input',{}).get('file_path',''); sys.exit(2 if any(p in path for p in ['.env', 'package-lock.json', '.git/']) else 0)\""
-          }
-        ]
-      }
-    ]
-  }
-}
-```
-
-## Learn more
-
-* For reference documentation on hooks, see [Hooks reference](/en/hooks).
-* For comprehensive security best practices and safety guidelines, see [Security Considerations](/en/hooks#security-considerations) in the hooks reference documentation.
-* For troubleshooting steps and debugging techniques, see [Debugging](/en/hooks#debugging) in the hooks reference
-  documentation.
-
-
---
-
-> To find navigation and other pages in this documentation, fetch the llms.txt file at: https://code.claude.com/docs/llms.txt
@@ -1,4 +1,5 @@
-<section dir="rtl">
+🌐 هذه ترجمة آلية. نرحب بالتصحيحات من المجتمع!
+
 <h1 align="center">
  <br>
  <a href="https://github.com/thedotmack/claude-mem">
@@ -13,7 +14,6 @@

 <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,7 +33,6 @@
  <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> •
@@ -44,8 +43,7 @@
  <a href="README.no.md">🇳🇴 Norsk</a>
 </p>

-<h4 align="center">أداة إضافية لـ <a href="https://claude.com/claude-code" target="_blank">Claude Code</a> تعمل على أتمتة تسجيل معلومات الجلسات السابقه، وضغطها, ثم حقن السياق ذي الصلة في الجلسات المستقبلية.
-</h4>
+<h4 align="center">نظام ضغط الذاكرة المستمرة المبني لـ <a href="https://claude.com/claude-code" target="_blank">Claude Code</a>.</h4>

 <p align="center">
  <a href="LICENSE">
@@ -82,27 +80,25 @@
  </a>
 </p>

-
 <p align="center">
-  <a href="#بداية-سريعة">بداية سريعة</a> •
+  <a href="#البدء-السريع">البدء السريع</a> •
  <a href="#كيف-يعمل">كيف يعمل</a> •
-  <a href="#أدوات-البحث-mcp-search-tools">أدوات البحث</a> •
-  <a href="#المستندات">التوثيق</a> •
+  <a href="#أدوات-البحث-mcp">أدوات البحث</a> •
+  <a href="#التوثيق">التوثيق</a> •
  <a href="#الإعدادات">الإعدادات</a> •
  <a href="#استكشاف-الأخطاء-وإصلاحها">استكشاف الأخطاء وإصلاحها</a> •
-  <a href="#الترخيص-license">الترخيص</a>
+  <a href="#الترخيص">الترخيص</a>
 </p>

-<p align="center"  dir="rtl">
-Claude-Mem هو نظام متطور مصمم لضغط وحفظ الذاكرة لسياق عمل Claude Code. وظيفته الأساسية هي جعل "كلود" يتذكر ما فعله في جلسات العمل السابقة بسلاسة، عبر تسجيل تحركاته، وإنشاء ملخصات ذكية، واستدعائها في الجلسات المستقبلية. هذا يضمن عدم ضياع سياق المشروع حتى لو أغلقت البرنامج وفتحته لاحقاً.
+<p align="center">
+  يحافظ Claude-Mem بسلاسة على السياق عبر الجلسات من خلال التقاط الملاحظات حول استخدام الأدوات تلقائيًا، وإنشاء ملخصات دلالية، وإتاحتها للجلسات المستقبلية. هذا يمكّن Claude من الحفاظ على استمرارية المعرفة حول المشاريع حتى بعد انتهاء الجلسات أو إعادة الاتصال.
 </p>

 ---

-## بداية سريعة 
+## البدء السريع

-للبدء، افتح "Claude Code" في مبنى الأوامر (Terminal) واكتب الأوامر التالية:
-<div dir="ltr"  align="left">
+ابدأ جلسة Claude Code جديدة في الطرفية وأدخل الأوامر التالية:

 ```
 > /plugin marketplace add thedotmack/claude-mem
@@ -110,34 +106,32 @@ Claude-Mem هو نظام متطور مصمم لضغط وحفظ الذاكرة ل
 > /plugin install claude-mem
 ```

-</div>
-
-بمجرد إعادة تشغيل Claude Code، سيتم استدعاء السياق من الجلسات السابقة تلقائيا عند الحاجة.
+أعد تشغيل Claude Code. سيظهر السياق من الجلسات السابقة تلقائيًا في الجلسات الجديدة.

 **الميزات الرئيسية:**

- 🧠 **ذاكرة مستديمه**:  سياق عملك لا ينتهي بانتهاء الجلسة، بل ينتقل معك للجلسة التالية.
- 📊 **الكشف التدريجي** (Progressive Disclosure): نظام ذكي يستدعي المعلومات على طبقات، مما يمنحك رؤية واضحة لاستهلاك الـ "Tokens" (التكلفة).
- 🔍 **بحث سريع** - استعلم عن سجل مشروعك باستخدام خاصية `mem-search`.
- 🖥️ **واجهة مستخدم ويب** - رؤية معلومات الذاكرة مع  تحديث فوري عبر المتصفح من خلال الرابط: http://localhost:37777
- 💻 **تكامل مع Claude Desktop** - إمكانية البحث في الذاكرة مباشرة من واجهة Claude المكتبية
- 🔒 **التحكم في الخصوصية** - دعم وسم `<private>` لمنع النظام من تخزين أي معلومات حساسة.
- ⚙️ **إعدادات السياق** - تحكم دقيق في السياق (context) التي سيتم حقنها في سياق المحادثة.
- 🤖 **أتمتة كاملة:** - النظام يعمل في الخلفية دون الحاجة لتدخل يدوي منك.
- 🔗 **الاستشهادات** - رجوع إلى الملاحظات السابقة باستخدام (http://localhost:37777/api/observation/{id} أو عرض جميع المعلومات على http://localhost:37777)
- 🧪 **مزايا التجريبيه** - تجربة مميزات مثل "الوضع اللانهائي" (Endless Mode).
+- 🧠 **ذاكرة مستمرة** - يبقى السياق عبر الجلسات
+- 📊 **الكشف التدريجي** - استرجاع الذاكرة بطبقات مع رؤية تكلفة الرموز
+- 🔍 **بحث قائم على المهارات** - استعلم عن تاريخ مشروعك باستخدام مهارة mem-search
+- 🖥️ **واجهة مستخدم ويب** - بث الذاكرة المباشر على http://localhost:37777
+- 💻 **مهارة Claude Desktop** - ابحث في الذاكرة من محادثات Claude Desktop
+- 🔒 **التحكم في الخصوصية** - استخدم وسوم `<private>` لاستبعاد المحتوى الحساس من التخزين
+- ⚙️ **إعدادات السياق** - تحكم دقيق في السياق الذي يتم حقنه
+- 🤖 **تشغيل تلقائي** - لا يتطلب تدخلاً يدويًا
+- 🔗 **الاستشهادات** - رجوع إلى الملاحظات السابقة باستخدام المعرفات (الوصول عبر http://localhost:37777/api/observation/{id} أو عرض الكل في عارض الويب على http://localhost:37777)
+- 🧪 **قناة تجريبية** - جرّب الميزات التجريبية مثل Endless Mode عبر تبديل الإصدار

 ---

-## المستندات 
+## التوثيق

-📚 **[عرض التوثيق الكامل](https://docs.claude-mem.ai/)** - تصفح على الموقع الرسمي
+📚 **[عرض التوثيق الكامل](docs/)** - تصفح مستندات markdown على GitHub

 ### البدء

 - **[دليل التثبيت](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/usage/search-tools)** - استعلم عن تاريخ مشروعك باللغة الطبيعية
 - **[الميزات التجريبية](https://docs.claude-mem.ai/beta-features)** - جرّب الميزات التجريبية مثل Endless Mode

 ### أفضل الممارسات
@@ -148,9 +142,9 @@ 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 سكريبتات خطافات
+- **[تطور البنية المعمارية](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
@@ -167,23 +161,24 @@ Claude-Mem هو نظام متطور مصمم لضغط وحفظ الذاكرة ل

 **المكونات الأساسية:**

-1. **5 برامج ربط (Hooks)** - SessionStart، UserPromptSubmit، PostToolUse، Stop، SessionEnd
-2. **تثبيت ذكي** - فاحص التبعيات المخزنة مؤقتًا
+1. **5 خطافات دورة الحياة** - SessionStart، UserPromptSubmit، PostToolUse، Stop، SessionEnd (6 سكريبتات خطافات)
+2. **تثبيت ذكي** - فاحص التبعيات المخزنة مؤقتًا (سكريبت ما قبل الخطاف، ليس خطاف دورة حياة)
 3. **خدمة العامل** - HTTP API على المنفذ 37777 مع واجهة مستخدم عارض الويب و10 نقاط نهاية للبحث، تديرها Bun
 4. **قاعدة بيانات SQLite** - تخزن الجلسات، الملاحظات، الملخصات
 5. **مهارة mem-search** - استعلامات اللغة الطبيعية مع الكشف التدريجي
-6. **قاعدة بيانات المتجهات Chroma** - البحث الدلالي الهجين + الكلمات المفتاحية لاسترجاع السياق الذكي
+6. **قاعدة بيانات المتجهات Chroma** - البحث المختلط الدلالي + الكلمات المفتاحية لاسترجاع السياق الذكي

 انظر [نظرة عامة على البنية المعمارية](https://docs.claude-mem.ai/architecture/overview) للتفاصيل.

 ---

-## أدوات البحث (MCP Search Tools)
+## مهارة mem-search
+
 يوفر Claude-Mem بحثًا ذكيًا من خلال مهارة mem-search التي تُستدعى تلقائيًا عندما تسأل عن العمل السابق:

 **كيف يعمل:**
 - فقط اسأل بشكل طبيعي: *"ماذا فعلنا في الجلسة الأخيرة؟"* أو *"هل أصلحنا هذا الخطأ من قبل؟"*
- يستدعي Claude تلقائيًا خاصية mem-search للعثور على السياق ذي الصلة
+- يستدعي Claude تلقائيًا مهارة mem-search للعثور على السياق ذي الصلة

 **عمليات البحث المتاحة:**

@@ -198,7 +193,7 @@ Claude-Mem هو نظام متطور مصمم لضغط وحفظ الذاكرة ل
 9. **الجدول الزمني حسب الاستعلام** - البحث عن الملاحظات والحصول على سياق الجدول الزمني حول أفضل تطابق
 10. **مساعدة API** - الحصول على توثيق API البحث

-**أمثلة على الاستعلامات:**
+**أمثلة على استعلامات اللغة الطبيعية:**

 ```
 "What bugs did we fix last session?"
@@ -224,7 +219,8 @@ Claude-Mem هو نظام متطور مصمم لضغط وحفظ الذاكرة ل

 - **Node.js**: 18.0.0 أو أعلى
 - **Claude Code**: أحدث إصدار مع دعم الإضافات
- **Bun & uv**: (يتم تثبيتهما تلقائياً) لإدارة العمليات والبحث المتجه.
+- **Bun**: بيئة تشغيل JavaScript ومدير العمليات (يُثبت تلقائيًا إذا كان مفقودًا)
+- **uv**: مدير حزم Python للبحث المتجهي (يُثبت تلقائيًا إذا كان مفقودًا)
 - **SQLite 3**: للتخزين المستمر (مدمج)

 ---
@@ -245,7 +241,7 @@ Claude-Mem هو نظام متطور مصمم لضغط وحفظ الذاكرة ل

 ## استكشاف الأخطاء وإصلاحها

-إذا واجهت مشكلة، اشرحها لـ Claude وسيقوم بتشغيل خاصية troubleshoot لإصلاحها ذاتياً.
+إذا واجهت مشكلات، صِف المشكلة لـ Claude وستقوم مهارة troubleshoot تلقائيًا بتشخيصها وتوفير الإصلاحات.

 انظر **[دليل استكشاف الأخطاء وإصلاحها](https://docs.claude-mem.ai/troubleshooting)** للمشكلات الشائعة والحلول.

@@ -254,29 +250,27 @@ Claude-Mem هو نظام متطور مصمم لضغط وحفظ الذاكرة ل
 ## تقارير الأخطاء

 أنشئ تقارير أخطاء شاملة باستخدام المولّد الآلي:
-<div align=left>

 ```bash
 cd ~/.claude/plugins/marketplaces/thedotmack
 npm run bug-report
 ```
-</div>

 ## المساهمة

 المساهمات مرحب بها! يُرجى:

-1. عمل Fork للمشروع (Repository)
-2. إنشاء فرع (branch)
+1. عمل Fork للمستودع
+2. إنشاء فرع ميزة
 3. إجراء التغييرات مع الاختبارات
-4. تحديث المستندات عند الحاجه
+4. تحديث التوثيق
 5. تقديم Pull Request

 انظر [دليل التطوير](https://docs.claude-mem.ai/development) لسير عمل المساهمة.

 ---

-## الترخيص (License)
+## الترخيص

 هذا المشروع مرخص بموجب **ترخيص GNU Affero العام الإصدار 3.0** (AGPL-3.0).

@@ -304,6 +298,4 @@ npm run bug-report

 ---

-**مبني باستخدام Claude Agent SDK** | **مدعوم بواسطة Claude Code** | **صُنع باستخدام TypeScript**
-
-</section>
+**مبني باستخدام Claude Agent SDK** | **مدعوم بواسطة Claude Code** | **صُنع باستخدام TypeScript**
@@ -15,7 +15,6 @@

 <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,7 +34,6 @@
  <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> •
@@ -128,7 +126,7 @@ Claude Code পুনরায় চালু করুন। পূর্ব

 ## ডকুমেন্টেশন

-📚 **[সম্পূর্ণ ডকুমেন্টেশন দেখুন](https://docs.claude-mem.ai/)** - অফিসিয়াল ওয়েবসাইটে ব্রাউজ করুন
+📚 **[সম্পূর্ণ ডকুমেন্টেশন দেখুন](docs/)** - GitHub-এ markdown ডক্স ব্রাউজ করুন

 ### শুরু করা

@@ -15,7 +15,6 @@

 <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,7 +34,6 @@
  <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> •
@@ -128,7 +126,7 @@ Restartujte Claude Code. Kontext z předchozích sezení se automaticky objeví

 ## Dokumentace

-📚 **[Zobrazit kompletní dokumentaci](https://docs.claude-mem.ai/)** - Procházet na oficiálních stránkách
+📚 **[Zobrazit kompletní dokumentaci](docs/)** - Procházejte dokumentaci v markdown na GitHubu

 ### Začínáme

@@ -15,7 +15,6 @@

 <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,7 +34,6 @@
  <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> •
@@ -128,7 +126,7 @@ Genstart Claude Code. Kontekst fra tidligere sessioner vil automatisk vises i ny

 ## Dokumentation

-📚 **[Se Fuld Dokumentation](https://docs.claude-mem.ai/)** - Gennemse på den officielle hjemmeside
+📚 **[Se Fuld Dokumentation](docs/)** - Gennemse markdown-dokumenter på GitHub

 ### Kom Godt I Gang

@@ -15,7 +15,6 @@

 <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,7 +34,6 @@
  <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> •
@@ -128,7 +126,7 @@ Starten Sie Claude Code neu. Kontext aus vorherigen Sitzungen wird automatisch i

 ## Dokumentation

-📚 **[Vollständige Dokumentation anzeigen](https://docs.claude-mem.ai/)** - Auf der offiziellen Website durchsuchen
+📚 **[Vollständige Dokumentation anzeigen](docs/)** - Markdown-Dokumentation auf GitHub durchsuchen

 ### Erste Schritte

@@ -15,7 +15,6 @@

 <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,7 +34,6 @@
  <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> •
@@ -128,7 +126,7 @@

 ## Τεκμηρίωση

-📚 **[Προβολή Πλήρους Τεκμηρίωσης](https://docs.claude-mem.ai/)** - Περιήγηση στον επίσημο ιστότοπο
+📚 **[Προβολή Πλήρους Τεκμηρίωσης](docs/)** - Περιήγηση στα markdown έγγραφα στο GitHub

 ### Ξεκινώντας

@@ -16,7 +16,6 @@

 <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> •
@@ -36,7 +35,6 @@
  <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 +127,7 @@ Reinicia Claude Code. El contexto de sesiones anteriores aparecerá automáticam

 ## Documentación

-📚 **[Ver Documentación Completa](https://docs.claude-mem.ai/)** - Navegar en el sitio web oficial
+📚 **[Ver Documentación Completa](docs/)** - Explora documentos markdown en GitHub

 ### Primeros Pasos

@@ -14,7 +14,6 @@

 <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,7 +33,6 @@
  <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 +125,7 @@ Käynnistä Claude Code uudelleen. Aiempien istuntojen konteksti ilmestyy automa

 ## Dokumentaatio

-📚 **[Näytä täydellinen dokumentaatio](https://docs.claude-mem.ai/)** - Selaa virallisella verkkosivustolla
+📚 **[Näytä täydellinen dokumentaatio](docs/)** - Selaa markdown-dokumentteja GitHubissa

 ### Aloitus

@@ -15,7 +15,6 @@

 <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,7 +34,6 @@
  <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> •
@@ -128,7 +126,7 @@ Redémarrez Claude Code. Le contexte des sessions précédentes apparaîtra auto

 ## Documentation

-📚 **[Voir la documentation complète](https://docs.claude-mem.ai/)** - Parcourir sur le site officiel
+📚 **[Voir la documentation complète](docs/)** - Parcourez la documentation markdown sur GitHub

 ### Pour commencer

@@ -14,7 +14,6 @@

 <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,7 +33,6 @@
  <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 +125,7 @@

 ## תיעוד

-📚 **[צפה בתיעוד המלא](https://docs.claude-mem.ai/)** - דפדף באתר הרשמי
+📚 **[צפה בתיעוד המלא](docs/)** - עיין במסמכי markdown ב-GitHub

 ### תחילת העבודה

@@ -15,7 +15,6 @@

 <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,7 +34,6 @@
  <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> •
@@ -128,7 +126,7 @@ Claude Code को पुनः आरंभ करें। पिछले स

 ## दस्तावेज़ीकरण

-📚 **[पूर्ण दस्तावेज़ीकरण देखें](https://docs.claude-mem.ai/)** - आधिकारिक वेबसाइट पर ब्राउज़ करें
+📚 **[पूर्ण दस्तावेज़ीकरण देखें](docs/)** - GitHub पर markdown दस्तावेज़ ब्राउज़ करें

 ### शुरुआत करना

@@ -15,7 +15,6 @@

 <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,7 +34,6 @@
  <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> •
@@ -128,7 +126,7 @@ Indítsa újra a Claude Code-ot. A korábbi munkamenetek kontextusa automatikusa

 ## Dokumentáció

-📚 **[Teljes dokumentáció megtekintése](https://docs.claude-mem.ai/)** - Böngészés a hivatalos weboldalon
+📚 **[Teljes dokumentáció megtekintése](docs/)** - Markdown dokumentumok böngészése GitHub-on

 ### Első lépések

@@ -15,7 +15,6 @@

 <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,7 +34,6 @@
  <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> •
@@ -128,7 +126,7 @@ Restart Claude Code. Konteks dari sesi sebelumnya akan secara otomatis muncul di

 ## Dokumentasi

-📚 **[Lihat Dokumentasi Lengkap](https://docs.claude-mem.ai/)** - Jelajahi di situs web resmi
+📚 **[Lihat Dokumentasi Lengkap](docs/)** - Telusuri dokumen markdown di GitHub

 ### Memulai

@@ -15,7 +15,6 @@

 <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,7 +34,6 @@
  <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> •
@@ -128,7 +126,7 @@ Riavvia Claude Code. Il contesto delle sessioni precedenti apparirà automaticam

 ## Documentazione

-📚 **[Visualizza Documentazione Completa](https://docs.claude-mem.ai/)** - Sfoglia sul sito ufficiale
+📚 **[Visualizza Documentazione Completa](docs/)** - Sfoglia i documenti markdown su GitHub

 ### Per Iniziare

@@ -15,7 +15,6 @@

 <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,7 +34,6 @@
  <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> •
@@ -128,7 +126,7 @@ Claude Codeを再起動します。以前のセッションからのコンテキ

 ## ドキュメント

-📚 **[完全なドキュメントを見る](https://docs.claude-mem.ai/)** - 公式ウェブサイトで閲覧
+📚 **[完全なドキュメントを見る](docs/)** - GitHubでマークダウンドキュメントを閲覧

 ### はじめに

@@ -214,7 +212,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)**を参照してください。

 ---

@@ -232,13 +230,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)**を参照してください。

 ---

@@ -246,7 +244,7 @@ Endless Modeと試用方法の詳細については、**[ベータ機能ドキ

 問題が発生した場合は、Claudeに問題を説明すると、troubleshootスキルが自動的に診断して修正を提供します。

-よくある問題と解決策については、**[トラブルシューティングガイド](https://docs.claude-mem.ai/troubleshooting)** を参照してください。
+よくある問題と解決策については、**[トラブルシューティングガイド](https://docs.claude-mem.ai/troubleshooting)**を参照してください。

 ---

@@ -288,7 +286,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)を参照してください。

 ---

@@ -301,4 +299,4 @@ Copyright (C) 2025 Alex Newman (@thedotmack). All rights reserved.

 ---

-**Claude Agent SDKで構築** | **Claude Codeで動作** | **TypeScriptで作成**
+**Claude Agent SDKで構築** | **Claude Codeで動作** | **TypeScriptで作成**
@@ -15,7 +15,6 @@

 <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,7 +34,6 @@
  <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> •
@@ -116,19 +114,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와 같은 실험적 기능 사용

 ---

 ## 문서

-📚 **[전체 문서 보기](https://docs.claude-mem.ai/)** - 공식 웹사이트에서 찾아보기
+📚 **[전체 문서 보기](docs/)** - GitHub에서 마크다운 문서 탐색

 ### 시작하기

@@ -14,7 +14,6 @@

 <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,7 +33,6 @@
  <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 +125,7 @@ Herstart Claude Code. Context van eerdere sessies verschijnt automatisch in nieu

 ## Documentatie

-📚 **[Bekijk Volledige Documentatie](https://docs.claude-mem.ai/)** - Bladeren op de officiële website
+📚 **[Bekijk Volledige Documentatie](docs/)** - Blader door markdown documenten op GitHub

 ### Aan de Slag

@@ -15,7 +15,6 @@

 <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,7 +34,6 @@
  <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> •
@@ -128,7 +126,7 @@ Start Claude Code på nytt. Kontekst fra tidligere økter vil automatisk vises i

 ## Dokumentasjon

-📚 **[Se Full Dokumentasjon](https://docs.claude-mem.ai/)** - Bla gjennom på det offisielle nettstedet
+📚 **[Se Full Dokumentasjon](docs/)** - Bla gjennom markdown-dokumenter på GitHub

 ### Komme I Gang

@@ -14,7 +14,6 @@

 <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,7 +33,6 @@
  <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 +125,7 @@ Uruchom ponownie Claude Code. Kontekst z poprzednich sesji automatycznie pojawi

 ## Dokumentacja

-📚 **[Wyświetl Pełną Dokumentację](https://docs.claude-mem.ai/)** - Przeglądaj na oficjalnej stronie
+📚 **[Wyświetl Pełną Dokumentację](docs/)** - Przeglądaj dokumentację markdown na GitHub

 ### Pierwsze Kroki

@@ -15,7 +15,6 @@

 <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,7 +34,6 @@
  <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> •
@@ -128,7 +126,7 @@ Reinicie o Claude Code. O contexto de sessões anteriores aparecerá automaticam

 ## Documentação

-📚 **[Ver Documentação Completa](https://docs.claude-mem.ai/)** - Navegar no site oficial
+📚 **[Ver Documentação Completa](docs/)** - Navegue pelos documentos markdown no GitHub

 ### Começando

@@ -15,7 +15,6 @@

 <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,7 +34,6 @@
  <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> •
@@ -128,7 +126,7 @@ Reporniți Claude Code. Contextul din sesiunile anterioare va apărea automat î

 ## Documentație

-📚 **[Vizualizați Documentația Completă](https://docs.claude-mem.ai/)** - Răsfoiți pe site-ul oficial
+📚 **[Vizualizați Documentația Completă](docs/)** - Răsfoiți documentele markdown pe GitHub

 ### Introducere

@@ -15,7 +15,6 @@

 <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,7 +34,6 @@
  <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> •
@@ -128,7 +126,7 @@

 ## Документация

-📚 **[Просмотреть полную документацию](https://docs.claude-mem.ai/)** - Просмотр на официальном сайте
+📚 **[Просмотреть полную документацию](docs/)** - Просмотр markdown-документов на GitHub

 ### Начало работы

@@ -15,7 +15,6 @@

 <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,7 +34,6 @@
  <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> •
@@ -128,7 +126,7 @@ Starta om Claude Code. Kontext från tidigare sessioner kommer automatiskt att v

 ## Dokumentation

-📚 **[Visa fullständig dokumentation](https://docs.claude-mem.ai/)** - Bläddra på den officiella webbplatsen
+📚 **[Visa fullständig dokumentation](docs/)** - Bläddra bland markdown-dokument på GitHub

 ### Komma igång

@@ -14,7 +14,6 @@

 <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,7 +33,6 @@
  <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 +125,7 @@

 ## เอกสาร

-📚 **[ดูเอกสารฉบับเต็ม](https://docs.claude-mem.ai/)** - เรียกดูบนเว็บไซต์อย่างเป็นทางการ
+📚 **[ดูเอกสารฉบับเต็ม](docs/)** - เรียกดูเอกสาร markdown บน GitHub

 ### เริ่มต้นใช้งาน

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

 <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,7 +33,6 @@
  <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 +125,7 @@ Claude Code'u yeniden başlatın. Önceki oturumlardaki bağlam otomatik olarak

 ## Dokümantasyon

-📚 **[Tam Dokümantasyonu Görüntüle](https://docs.claude-mem.ai/)** - Resmi web sitesinde göz atın
+📚 **[Tam Dokümantasyonu Görüntüle](docs/)** - GitHub'da markdown dökümanlarına göz atın

 ### Başlarken

@@ -15,7 +15,6 @@

 <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,7 +34,6 @@
  <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> •
@@ -128,7 +126,7 @@

 ## Документація

-📚 **[Переглянути повну документацію](https://docs.claude-mem.ai/)** - Переглянути на офіційному сайті
+📚 **[Переглянути повну документацію](docs/)** - Переглядайте markdown документи на GitHub

 ### Початок роботи

@@ -1,311 +0,0 @@
-<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>
@@ -15,7 +15,6 @@

 <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,7 +34,6 @@
  <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> •
@@ -128,7 +126,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 Đủ](https://docs.claude-mem.ai/)** - Duyệt trên trang web chính thức
+📚 **[Xem Tài Liệu Đầy Đủ](docs/)** - Duyệt tài liệu markdown trên GitHub

 ### Bắt Đầu

@@ -1,311 +0,0 @@
-🌐 這是自動翻譯。歡迎社群貢獻修正！
-
---
-<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 開發**
@@ -15,7 +15,6 @@

 <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,7 +34,6 @@
  <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> •
@@ -128,7 +126,7 @@

 ## 文档

-📚 **[查看完整文档](https://docs.claude-mem.ai/)** - 在官方网站浏览
+📚 **[查看完整文档](docs/)** - 在 GitHub 上浏览 Markdown 文档

 ### 入门指南

@@ -214,7 +212,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)**了解无尽模式的详细信息和试用方法。

 ---

@@ -232,13 +230,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)**了解构建说明、测试和贡献工作流程。

 ---

@@ -246,7 +244,7 @@ Claude-Mem 提供**测试版渠道**,包含实验性功能,如**无尽模式**(

 如果遇到问题,向 Claude 描述问题,troubleshoot 技能将自动诊断并提供修复方案。

-详见 **[故障排除指南](https://docs.claude-mem.ai/troubleshooting)** 了解常见问题和解决方案。
+详见**[故障排除指南](https://docs.claude-mem.ai/troubleshooting)**了解常见问题和解决方案。

 ---

@@ -303,4 +301,4 @@ Copyright (C) 2025 Alex Newman (@thedotmack)。保留所有权利。

 **使用 Claude Agent SDK 构建** | **由 Claude Code 驱动** | **使用 TypeScript 制作**

---
+---
@@ -1,305 +0,0 @@
-🌐 Esta é uma tradução manual por mig4ng. Correções da comunidade são bem-vindas!
-
---
-<h1 align="center">
-  <br>
-  <a href="https://github.com/thedotmack/claude-mem">
-    <picture>
-      <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/thedotmack/claude-mem/main/docs/public/claude-mem-logo-for-dark-mode.webp">
-      <source media="(prefers-color-scheme: light)" srcset="https://raw.githubusercontent.com/thedotmack/claude-mem/main/docs/public/claude-mem-logo-for-light-mode.webp">
-      <img src="https://raw.githubusercontent.com/thedotmack/claude-mem/main/docs/public/claude-mem-logo-for-light-mode.webp" alt="Claude-Mem" width="400">
-    </picture>
-  </a>
-  <br>
-</h1>
-
-<p align="center">
-  <a href="README.zh.md">🇨🇳 中文</a> •
-  <a href="README.zh-tw.md">🇹🇼 繁體中文</a> •
-  <a href="README.ja.md">🇯🇵 日本語</a> •
-  <a href="README.pt.md">🇵🇹 Português</a> •
-  <a href="README.pt-br.md">🇧🇷 Português (Brasil)</a> •
-  <a href="README.ko.md">🇰🇷 한국어</a> •
-  <a href="README.es.md">🇪🇸 Español</a> •
-  <a href="README.de.md">🇩🇪 Deutsch</a> •
-  <a href="README.fr.md">🇫🇷 Français</a>
-  <a href="README.he.md">🇮🇱 עברית</a> •
-  <a href="README.ar.md">🇸🇦 العربية</a> •
-  <a href="README.ru.md">🇷🇺 Русский</a> •
-  <a href="README.pl.md">🇵🇱 Polski</a> •
-  <a href="README.cs.md">🇨🇿 Čeština</a> •
-  <a href="README.nl.md">🇳🇱 Nederlands</a> •
-  <a href="README.tr.md">🇹🇷 Türkçe</a> •
-  <a href="README.uk.md">🇺🇦 Українська</a> •
-  <a href="README.vi.md">🇻🇳 Tiếng Việt</a> •
-  <a href="README.id.md">🇮🇩 Indonesia</a> •
-  <a href="README.th.md">🇹🇭 ไทย</a> •
-  <a href="README.hi.md">🇮🇳 हिन्दी</a> •
-  <a href="README.bn.md">🇧🇩 বাংলা</a> •
-  <a href="README.ur.md">🇵🇰 اردو</a> •
-  <a href="README.ro.md">🇷🇴 Română</a> •
-  <a href="README.sv.md">🇸🇪 Svenska</a> •
-  <a href="README.it.md">🇮🇹 Italiano</a> •
-  <a href="README.el.md">🇬🇷 Ελληνικά</a> •
-  <a href="README.hu.md">🇭🇺 Magyar</a> •
-  <a href="README.fi.md">🇫🇮 Suomi</a> •
-  <a href="README.da.md">🇩🇰 Dansk</a> •
-  <a href="README.no.md">🇳🇴 Norsk</a>
-</p>
-
-<h4 align="center">Sistema de compressão de memória persistente construído para <a href="https://claude.com/claude-code" target="_blank">Claude Code</a>.</h4>
-
-<p align="center">
-  <a href="LICENSE">
-    <img src="https://img.shields.io/badge/License-AGPL%203.0-blue.svg" alt="License">
-  </a>
-  <a href="package.json">
-    <img src="https://img.shields.io/badge/version-6.5.0-green.svg" alt="Version">
-  </a>
-  <a href="package.json">
-    <img src="https://img.shields.io/badge/node-%3E%3D18.0.0-brightgreen.svg" alt="Node">
-  </a>
-  <a href="https://github.com/thedotmack/awesome-claude-code">
-    <img src="https://awesome.re/mentioned-badge.svg" alt="Mentioned in Awesome Claude Code">
-  </a>
-</p>
-
-<p align="center">
-  <a href="https://trendshift.io/repositories/15496" target="_blank">
-    <picture>
-      <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/thedotmack/claude-mem/main/docs/public/trendshift-badge-dark.svg">
-      <source media="(prefers-color-scheme: light)" srcset="https://raw.githubusercontent.com/thedotmack/claude-mem/main/docs/public/trendshift-badge.svg">
-      <img src="https://raw.githubusercontent.com/thedotmack/claude-mem/main/docs/public/trendshift-badge.svg" alt="thedotmack/claude-mem | Trendshift" width="250" height="55"/>
-    </picture>
-  </a>
-</p>
-
-<br>
-
-<p align="center">
-  <a href="https://github.com/thedotmack/claude-mem">
-    <picture>
-      <img src="https://raw.githubusercontent.com/thedotmack/claude-mem/main/docs/public/cm-preview.gif" alt="Claude-Mem Preview" width="800">
-    </picture>
-  </a>
-</p>
-
-<p align="center">
-  <a href="#início-rápido">Início Rápido</a> •
-  <a href="#como-funciona">Como Funciona</a> •
-  <a href="#ferramentas-de-procura-mcp">Ferramentas de Procura</a> •
-  <a href="#documentação">Documentação</a> •
-  <a href="#configuração">Configuração</a> •
-  <a href="#solução-de-problemas">Solução de Problemas</a> •
-  <a href="#licença">Licença</a>
-</p>
-
-<p align="center">
-  Claude-Mem preserva o contexto perfeitamente entre sessões, capturando automaticamente observações de uso de ferramentas, gerando resumos semânticos e disponibilizando-os para sessões futuras. Isso permite que Claude mantenha a continuidade do conhecimento sobre projetos mesmo após o término ou reconexão de sessões.
-</p>
-
---
-
-## Início Rápido
-
-Inicie uma nova sessão do Claude Code no terminal e digite os seguintes comandos:
-
-```
-> /plugin marketplace add thedotmack/claude-mem
-
-> /plugin install claude-mem
-```
-
-Reinicie o Claude Code. O contexto de sessões anteriores aparecerá automaticamente em novas sessões.
-
-**Principais Recursos:**
-
- 🧠 **Memória Persistente** - O contexto sobrevive entre sessões
- 📊 **Divulgação Progressiva** - Recuperação de memória em camadas com visibilidade de custo de tokens
- 🔍 **Procura Baseada em Skill** - Consulte seu histórico de projeto com a skill mem-search
- 🖥️ **Interface Web de Visualização** - Fluxo de memória em tempo real em http://localhost:37777
- 💻 **Skill para Claude Desktop** - Busque memória em conversas do Claude Desktop
- 🔒 **Controle de Privacidade** - Use tags `<private>` para excluir conteúdo sensível do armazenamento
- ⚙️ **Configuração de Contexto** - Controle refinado sobre qual contexto é injetado
- 🤖 **Operação Automática** - Nenhuma intervenção manual necessária
- 🔗 **Citações** - Referencie observações passadas com IDs (acesse via http://localhost:37777/api/observation/{id} ou visualize todas no visualizador web em http://localhost:37777)
- 🧪 **Canal Beta** - Experimente recursos experimentais como o Endless Mode através da troca de versões
-
---
-
-## Documentação
-
-📚 **[Ver Documentação Completa](https://docs.claude-mem.ai/)** - Navegar no site oficial
-
-### Começando
-
- **[Guia de Instalação](https://docs.claude-mem.ai/installation)** - Início rápido e instalação avançada
- **[Guia de Uso](https://docs.claude-mem.ai/usage/getting-started)** - Como Claude-Mem funciona automaticamente
- **[Ferramentas de Procura](https://docs.claude-mem.ai/usage/search-tools)** - Consulte seu histórico de projeto com linguagem natural
- **[Recursos Beta](https://docs.claude-mem.ai/beta-features)** - Experimente recursos experimentais como o Endless Mode
-
-### Melhores Práticas
-
- **[Engenharia de Contexto](https://docs.claude-mem.ai/context-engineering)** - Princípios de otimização de contexto para agentes de IA
- **[Divulgação Progressiva](https://docs.claude-mem.ai/progressive-disclosure)** - Filosofia por trás da estratégia de preparação de contexto do Claude-Mem
-
-### Arquitetura
-
- **[Visão Geral](https://docs.claude-mem.ai/architecture/overview)** - Componentes do sistema e fluxo de dados
- **[Evolução da Arquitetura](https://docs.claude-mem.ai/architecture-evolution)** - A jornada da v3 à v5
- **[Arquitetura de Hooks](https://docs.claude-mem.ai/hooks-architecture)** - Como Claude-Mem usa hooks de ciclo de vida
- **[Referência de Hooks](https://docs.claude-mem.ai/architecture/hooks)** - 7 scripts de hook explicados
- **[Serviço Worker](https://docs.claude-mem.ai/architecture/worker-service)** - API HTTP e gerenciamento do Bun
- **[Banco de Dados](https://docs.claude-mem.ai/architecture/database)** - Schema SQLite e Procura FTS5
- **[Arquitetura de Procura](https://docs.claude-mem.ai/architecture/search-architecture)** - Procura híbrida com banco de dados vetorial Chroma
-
-### Configuração e Desenvolvimento
-
- **[Configuração](https://docs.claude-mem.ai/configuration)** - Variáveis de ambiente e configurações
- **[Desenvolvimento](https://docs.claude-mem.ai/development)** - Build, testes e contribuição
- **[Solução de Problemas](https://docs.claude-mem.ai/troubleshooting)** - Problemas comuns e soluções
-
---
-
-## Como Funciona
-
-**Componentes Principais:**
-
-1. **5 Hooks de Ciclo de Vida** - SessionStart, UserPromptSubmit, PostToolUse, Stop, SessionEnd (6 scripts de hook)
-2. **Instalação Inteligente** - Verificador de dependências em cache (script pré-hook, não um hook de ciclo de vida)
-3. **Serviço Worker** - API HTTP na porta 37777 com interface de visualização web e 10 endpoints de Procura, gerenciado pelo Bun
-4. **Banco de Dados SQLite** - Armazena sessões, observações, resumos
-5. **Skill mem-search** - Consultas em linguagem natural com divulgação progressiva
-6. **Banco de Dados Vetorial Chroma** - Procura híbrida semântica + palavra-chave para recuperação inteligente de contexto
-
-Veja [Visão Geral da Arquitetura](https://docs.claude-mem.ai/architecture/overview) para detalhes.
-
---
-
-## Skill mem-search
-
-Claude-Mem fornece Procura inteligente através da skill mem-search que se auto-invoca quando você pergunta sobre trabalhos anteriores:
-
-**Como Funciona:**
- Pergunte naturalmente: *"O que fizemos na última sessão?"* ou *"Já corrigimos esse bug antes?"*
- Claude invoca automaticamente a skill mem-search para encontrar contexto relevante
-
-**Operações de Procura Disponíveis:**
-
-1. **Search Observations** - Procura de texto completo em observações
-2. **Search Sessions** - Procura de texto completo em resumos de sessão
-3. **Search Prompts** - Procura em solicitações brutas do usuário
-4. **By Concept** - Encontre por tags de conceito (discovery, problem-solution, pattern, etc.)
-5. **By File** - Encontre observações que referenciam arquivos específicos
-6. **By Type** - Encontre por tipo (decision, bugfix, feature, refactor, discovery, change)
-7. **Recent Context** - Obtenha contexto de sessão recente para um projeto
-8. **Timeline** - Obtenha linha do tempo unificada de contexto em torno de um ponto específico no tempo
-9. **Timeline by Query** - Busque observações e obtenha contexto de linha do tempo em torno da melhor correspondência
-10. **API Help** - Obtenha documentação da API de Procura
-
-**Exemplos de Consultas em Linguagem Natural:**
-
-```
-"Quais bugs corrigimos na última sessão?"
-"Como implementamos a autenticação?"
-"Quais mudanças foram feitas em worker-service.ts?"
-"Mostre-me trabalhos recentes neste projeto"
-"O que estava acontecendo quando adicionamos a interface de visualização?"
-```
-
-Veja [Guia de Ferramentas de Procura](https://docs.claude-mem.ai/usage/search-tools) para exemplos detalhados.
-
---
-
-## Recursos Beta
-
-Claude-Mem oferece um **canal beta** com recursos experimentais como **Endless Mode** (arquitetura de memória biomimética para sessões estendidas). Alterne entre versões estável e beta pela interface de visualização web em http://localhost:37777 → Settings.
-
-Veja **[Documentação de Recursos Beta](https://docs.claude-mem.ai/beta-features)** para detalhes sobre o Endless Mode e como experimentá-lo.
-
---
-
-## Requisitos do Sistema
-
- **Node.js**: 18.0.0 ou superior
- **Claude Code**: Versão mais recente com suporte a plugins
- **Bun**: Runtime JavaScript e gerenciador de processos (instalado automaticamente se ausente)
- **uv**: Gerenciador de pacotes Python para Procura vetorial (instalado automaticamente se ausente)
- **SQLite 3**: Para armazenamento persistente (incluído)
-
---
-
-## Configuração
-
-As configurações são gerenciadas em `~/.claude-mem/settings.json` (criado automaticamente com valores padrão na primeira execução). Configure modelo de IA, porta do worker, diretório de dados, nível de log e configurações de injeção de contexto.
-
-Veja o **[Guia de Configuração](https://docs.claude-mem.ai/configuration)** para todas as configurações disponíveis e exemplos.
-
---
-
-## Desenvolvimento
-
-Veja o **[Guia de Desenvolvimento](https://docs.claude-mem.ai/development)** para instruções de build, testes e fluxo de contribuição.
-
---
-
-## Solução de Problemas
-
-Se você estiver enfrentando problemas, descreva o problema para Claude e a skill troubleshoot diagnosticará automaticamente e fornecerá correções.
-
-Veja o **[Guia de Solução de Problemas](https://docs.claude-mem.ai/troubleshooting)** para problemas comuns e soluções.
-
---
-
-## Relatos de Bug
-
-Crie relatos de bug abrangentes com o gerador automatizado:
-
-```bash
-cd ~/.claude/plugins/marketplaces/thedotmack
-npm run bug-report
-```
-
-## Contribuindo
-
-Contribuições são bem-vindas! Por favor:
-
-1. Faça um fork do repositório
-2. Crie uma branch de feature
-3. Faça suas alterações com testes
-4. Atualize a documentação
-5. Envie um Pull Request
-
-Veja [Guia de Desenvolvimento](https://docs.claude-mem.ai/development) para o fluxo de contribuição.
-
---
-
-## Licença
-
-Este projeto está licenciado sob a **GNU Affero General Public License v3.0** (AGPL-3.0).
-
-Copyright (C) 2025 Alex Newman (@thedotmack). Todos os direitos reservados.
-
-Veja o arquivo [LICENSE](LICENSE) para detalhes completos.
-
-**O Que Isso Significa:**
-
- Você pode usar, modificar e distribuir este software livremente
- Se você modificar e implantar em um servidor de rede, você deve disponibilizar seu código-fonte
- Trabalhos derivados também devem ser licenciados sob AGPL-3.0
- NÃO HÁ GARANTIA para este software
-
-**Nota sobre Ragtime**: O diretório `ragtime/` é licenciado separadamente sob a **PolyForm Noncommercial License 1.0.0**. Veja [ragtime/LICENSE](ragtime/LICENSE) para detalhes.
-
---
-
-## Suporte
-
- **Documentação**: [docs/](docs/)
- **Issues**: [GitHub Issues](https://github.com/thedotmack/claude-mem/issues)
- **Repositório**: [github.com/thedotmack/claude-mem](https://github.com/thedotmack/claude-mem)
- **Autor**: Alex Newman ([@thedotmack](https://github.com/thedotmack))
-
---
-
-**Construído com Claude Agent SDK** | **Desenvolvido por Claude Code** | **Feito com TypeScript** | **Editado por mig4ng**
@@ -1,111 +0,0 @@
-# claude-mem Production Guide
-
-Practical guide based on 23 days of production usage with 3,400+ observations across two physical servers and 8 projects.
-
-## Recommended Settings
-
-| Setting | Default | Recommended | Why |
-|---------|---------|-------------|-----|
-| CLAUDE_MEM_MAX_CONCURRENT_AGENTS | 2 | 3 | Better throughput without overload |
-| CLAUDE_MEM_SEMANTIC_INJECT | true | true | Relevant context >> recent context |
-| CLAUDE_MEM_SEMANTIC_INJECT_LIMIT | 5 | 5 | Sweet spot for token cost vs coverage |
-| CLAUDE_MEM_TIER_ROUTING_ENABLED | true | true | ~52% cost savings, no quality loss |
-
-## Health Monitoring
-
-### Key metrics to watch
-
-| Metric | Healthy | Warning | Action |
-|--------|---------|---------|--------|
-| pending_messages (pending) | 0-5 | >10 | Check worker logs, may need restart |
-| pending_messages (failed) | 0 | >0 growing | Circuit-breaker may be tripping |
-| sdk_sessions (active) | 0-3 | >5 stuck | Orphan sessions, worker restart |
-| WAL size | <10 MB | >20 MB | Run `PRAGMA wal_checkpoint(TRUNCATE)` |
-| Chroma size | Growing slowly | Sudden jump | Check for sync loops |
-| Errors/day in logs | 0-2 | >10 | Investigate log patterns |
-
-### Quick health check
-
-```bash
-# Check worker status
-curl -s http://127.0.0.1:37777/api/health | python3 -m json.tool
-
-# Check database stats
-sqlite3 ~/.claude-mem/claude-mem.db "
-  SELECT 'observations' as metric, COUNT(*) as value FROM observations
-  UNION ALL SELECT 'summaries', COUNT(*) FROM session_summaries
-  UNION ALL SELECT 'pending', COUNT(*) FROM pending_messages WHERE status='pending'
-  UNION ALL SELECT 'active_sessions', COUNT(*) FROM sdk_sessions WHERE status='active';
-"
-```
-
-## Multi-Machine Setup
-
-If running claude-mem on multiple machines, use `claude-mem-sync` to keep observations in sync:
-
-```bash
-claude-mem-sync push <remote-host>    # local -> remote
-claude-mem-sync pull <remote-host>    # remote -> local
-claude-mem-sync sync <remote-host>    # bidirectional
-claude-mem-sync status <remote-host>  # compare counts
-```
-
-Deduplication is by `(created_at, title)` — safe to run repeatedly.
-
-## Growth Expectations
-
-Based on active daily development usage:
-
-| Metric | Per day | Per month | Notes |
-|--------|---------|-----------|-------|
-| Observations | ~120 | ~3,600 | Varies with coding activity |
-| Summaries | ~40 | ~1,200 | One per session |
-| SQLite | ~0.8 MB | ~24 MB | ~5 KB per observation |
-| Chroma | ~4 MB | ~120 MB | ~50 KB per observation (embeddings) |
-
-## Common Issues and Solutions
-
-### Summarize error loop
-
-**Symptom:** Repeated `[ERROR] Missing last_assistant_message` in logs.
-**Cause:** Transcript with no assistant messages triggers summary attempt that fails repeatedly.
-**Fix:** PR #1566 — skip summary when transcript is empty.
-
-### Chroma sync failures
-
-**Symptom:** `[ERROR] Batch add failed... IDs already exist`
-**Cause:** MCP timeout during add leaves partial writes; retry fails on existing IDs.
-**Fix:** PR #1566 — fallback to delete+add reconciliation.
-
-### Port conflict on startup
-
-**Symptom:** `Worker failed to start... Is port 37777 in use?`
-**Cause:** Two sessions starting simultaneously — HTTP check is non-atomic (TOCTOU race).
-**Fix:** PR #1566 — atomic socket bind on Unix.
-
-### Orphaned pending messages
-
-**Symptom:** `pending_messages` table growing with old entries for completed sessions.
-**Cause:** SIGTERM kills generator before queue is drained.
-**Fix:** PR #1567 — drain after deleteSession().
-
-### Context not relevant to current topic
-
-**Symptom:** Claude receives observations about CSS when you're asking about authentication.
-**Cause:** Default recency-based injection selects most recent, not most relevant.
-**Fix:** PR #1568 — semantic injection via Chroma on every prompt.
-
-## Log Analysis Tips
-
-```bash
-# Count errors by day
-grep '\[ERROR\]' ~/.claude-mem/logs/claude-mem-*.log | \
-  sed 's/\[20[0-9][0-9]-[0-9][0-9]-/\n&/g' | \
-  grep -oP '^\[20\d{2}-\d{2}-\d{2}' | sort | uniq -c
-
-# Find circuit-breaker trips
-grep 'circuit\|Circuit\|ABANDONED\|abandoned' ~/.claude-mem/logs/claude-mem-*.log
-
-# Check pending message health
-grep 'CLAIMED\|CONFIRMED\|FAILED\|ABANDONED' ~/.claude-mem/logs/claude-mem-$(date +%Y-%m-%d).log | tail -20
-```
@@ -85,4 +85,4 @@ npx mintlify dev

 **Simple Rule**:
 - `/docs/public/` = Official user documentation (Mintlify .mdx files) ← YOU ARE HERE
- `/docs/context/` = Internal docs, plans, references, audits
+- `/docs/context/` = Internal docs, plans, references, audits
@@ -248,164 +248,6 @@ search_observations({

 ---

-## MCP Architecture Simplification (December 2025)
-
-### The Problem: Complex MCP Implementation
-
-**Before:**
-```
-9+ MCP tools registered at session start:
- search_observations
- find_by_type
- find_by_file
- find_by_concept
- get_recent_context
- get_observation
- get_session
- get_prompt
- help
-
-Problems:
- Overlapping operations (search_observations vs find_by_type)
- Complex parameter schemas (~2,500 tokens in tool definitions)
- No built-in workflow guidance
- High cognitive load for Claude (which tool to use?)
- Code size: ~2,718 lines in mcp-server.ts
-```
-
-**The Insight:** Progressive disclosure should be built into tool design itself, not something Claude has to remember.
-
-### The Solution: 3-Layer Workflow
-
-**After:**
-```
-4 MCP tools following 3-layer workflow:
-
-1. __IMPORTANT - Workflow documentation (always visible)
-   "3-LAYER WORKFLOW (ALWAYS FOLLOW):
-    1. search(query) → Get index with IDs
-    2. timeline(anchor=ID) → Get context
-    3. get_observations([IDs]) → Fetch details
-    NEVER fetch full details without filtering first."
-
-2. search - Layer 1: Get index with IDs (~50-100 tokens/result)
-3. timeline - Layer 2: Get chronological context
-4. get_observations - Layer 3: Fetch full details (~500-1,000 tokens/result)
-
-Benefits:
- Progressive disclosure enforced by tool structure
- No overlapping operations
- Simple schemas (additionalProperties: true)
- Clear workflow pattern
- Code size: ~312 lines in mcp-server.ts (88% reduction)
- ~10x token savings
-```
-
-### Migration: Skill-Based Search Removed
-
-**Previously:** Used skill-based search
- mem-search skill invoked via natural language
- HTTP API called directly via curl
- Progressive disclosure through skill loading
- 17 skill documentation files
-
-**Now:** Removed skill-based approach
- MCP-only architecture
- Native MCP protocol (better Claude integration)
- Works with both Claude Desktop and Claude Code
- Simpler to maintain (no skill files)
- All 19 mem-search skill files removed (~2,744 lines)
-
-### Key Architectural Changes
-
-**MCP Server Refactor:**
-
-Before:
-```typescript
-// Complex parameter schemas
-{
-  name: "search_observations",
-  inputSchema: {
-    type: "object",
-    properties: {
-      query: { type: "string", description: "..." },
-      type: { type: "array", items: { enum: [...] } },
-      format: { enum: ["index", "full"] },
-      limit: { type: "number", minimum: 1, maximum: 100 },
-      // ... many more parameters
-    }
-  }
-}
-```
-
-After:
-```typescript
-// Simple schemas with workflow guidance
-{
-  name: "search",
-  description: "Step 1: Search memory. Returns index with IDs.",
-  inputSchema: {
-    type: "object",
-    properties: {},
-    additionalProperties: true  // Accept any parameters
-  }
-}
-```
-
-**Workflow Enforcement:**
-
-Before: Claude had to remember progressive disclosure pattern
-
-After: Tool structure makes it impossible to skip steps
- Can't get details without IDs from search
- Can't search without seeing __IMPORTANT reminder
- Timeline provides middle ground (context without full details)
-
-### Impact
-
-**Token Efficiency:**
-```
-Traditional: Fetch 20 observations upfront
-→ 10,000-20,000 tokens
-→ Only 2 observations relevant (90% waste)
-
-3-Layer Workflow:
-→ search (20 results): ~1,000-2,000 tokens
-→ Review index, identify 3 relevant IDs
-→ get_observations (3 IDs): ~1,500-3,000 tokens
-→ Total: 2,500-5,000 tokens (50-75% savings)
-```
-
-**Code Simplicity:**
- MCP server: 2,718 lines → 312 lines (88% reduction)
- Removed: 19 skill files (~2,744 lines)
- Net reduction: ~5,150 lines of code removed
-
-**User Experience:**
- Same natural language interaction
- Better token efficiency
- Clearer architecture
- Works identically on Claude Desktop and Claude Code
-
-### Design Philosophy
-
-**Progressive Disclosure Through Structure:**
-
-The 3-layer workflow embodies progressive disclosure at the architectural level:
-
-1. **Layer 1 (Index)** - "What exists?" - Cheap survey of options
-2. **Layer 2 (Timeline)** - "What was happening?" - Context around specific points
-3. **Layer 3 (Details)** - "Tell me everything" - Full details only when justified
-
-Each layer provides a decision point where Claude can:
- Stop if irrelevant
- Get more context if uncertain
- Dive deep if confident
-
-This makes it structurally difficult to waste tokens.
-
---
-
 ## v1-v2: The Naive Approach

 ### The First Attempt: Dump Everything
@@ -177,7 +177,7 @@ graph TB

 | Stage | Hook | Trigger | Purpose |
 |-------|------|---------|---------|
-| **1. SessionStart** | `context-hook.js` | User opens Claude Code | Inject prior context silently |
+| **1. SessionStart** | `context-hook.js` + `user-message-hook.js` | User opens Claude Code | Inject prior context, show UI messages |
 | **2. UserPromptSubmit** | `new-hook.js` | User submits a prompt | Create/get session, save prompt, init worker |
 | **3. PostToolUse** | `save-hook.js` | Claude uses any tool | Queue observation for AI compression |
 | **4. Stop** | `summary-hook.js` | User stops asking questions | Generate session summary |
@@ -194,16 +194,12 @@ Hooks are configured in `plugin/hooks/hooks.json`:
      "matcher": "startup|clear|compact",
      "hooks": [{
        "type": "command",
-        "command": "node ${CLAUDE_PLUGIN_ROOT}/scripts/smart-install.js",
+        "command": "node ${CLAUDE_PLUGIN_ROOT}/scripts/context-hook.js",
        "timeout": 300
      }, {
        "type": "command",
-        "command": "bun ${CLAUDE_PLUGIN_ROOT}/scripts/worker-service.cjs start",
-        "timeout": 60
-      }, {
-        "type": "command",
-        "command": "bun ${CLAUDE_PLUGIN_ROOT}/scripts/context-hook.js",
-        "timeout": 60
+        "command": "node ${CLAUDE_PLUGIN_ROOT}/scripts/user-message-hook.js",
+        "timeout": 10
      }]
    }],
    "UserPromptSubmit": [{
@@ -246,13 +242,8 @@ Hooks are configured in `plugin/hooks/hooks.json`:
 **Timing**: When user opens Claude Code or resumes session

 **Hooks Triggered** (in order):
-1. `smart-install.js` - Ensures dependencies are installed
-2. `worker-service.cjs start` - Starts the worker service
-3. `context-hook.js` - Fetches and silently injects prior session context
-
-<Note>
-As of Claude Code 2.1.0 (ultrathink update), SessionStart hooks no longer display user-visible messages. Context is silently injected via `hookSpecificOutput.additionalContext`.
-</Note>
+1. `context-hook.js` - Fetches and injects prior session context
+2. `user-message-hook.js` - Displays context info to user via stderr

 ### Sequence Diagram

@@ -315,6 +306,19 @@ sequenceDiagram

 **Implementation**: `src/hooks/context-hook.ts`

+### User Message Hook (`user-message-hook.js`)
+
+**Purpose**: Display helpful user messages during first-time setup or when viewing context.
+
+**Behavior**:
+- Shows first-time setup message when `node_modules` is missing
+- Displays formatted context information with colors
+- Provides tips for using claude-mem effectively
+- Shows link to viewer UI (`http://localhost:37777`)
+- Uses stderr as communication channel (only output available in Claude Code UI)
+
+**Implementation**: `src/hooks/user-message-hook.ts`
+
 ---

 ## Stage 2: UserPromptSubmit
@@ -45,19 +45,19 @@ Hook (stdin) → Database → Worker Service → SDK Processor → Database →
 4. **Output**: Processed summaries written back to database
 5. **Retrieval**: Next session's context hook reads summaries from database

-### Search Pipeline
+### Search Pipeline (v5.4.0+)
 ```
-User Query → MCP Tools Invoked → HTTP API → SessionSearch Service → FTS5 Database → Search Results → Claude
+User Query → mem-search Skill Invoked → HTTP API → SessionSearch Service → FTS5 Database → Search Results → Claude
 ```

 1. **User Query**: User asks naturally: "What bugs did we fix?"
-2. **MCP Tools Invoked**: Claude recognizes intent and invokes MCP search tools
-3. **HTTP API**: MCP tools call HTTP endpoint (e.g., `/api/search/observations`)
+2. **Skill Invoked**: Claude recognizes intent and invokes mem-search skill
+3. **HTTP API**: Skill uses curl to call HTTP endpoint (e.g., `/api/search/observations`)
 4. **SessionSearch**: Worker service queries FTS5 virtual tables
-5. **Format**: Results formatted and returned via MCP
+5. **Format**: Results formatted and returned to skill
 6. **Return**: Claude presents formatted results to user

-Uses 3-layer progressive disclosure: search → timeline → get_observations
+**Token Savings**: ~2,250 tokens per session vs MCP approach through progressive disclosure

 ## Session Lifecycle

@@ -106,7 +106,7 @@ pm2 logs claude-mem-worker    # View logs
 ```bash
 npm run worker:start    # Start worker
 npm run worker:stop     # Stop worker
-npm run worker:restart  # Restart worker
+claude-mem restart  # Restart worker
 npm run worker:status   # Check status
 npm run worker:logs     # View logs
 ```
@@ -305,7 +305,7 @@ No migration logic runs on subsequent sessions.
 | `pm2 list` | `npm run worker:status` | Shows worker status |
 | `pm2 start <script>` | `npm run worker:start` | Start worker |
 | `pm2 stop claude-mem-worker` | `npm run worker:stop` | Stop worker |
-| `pm2 restart claude-mem-worker` | `npm run worker:restart` | Restart worker |
+| `pm2 restart claude-mem-worker` | `claude-mem restart` | Restart worker |
 | `pm2 delete claude-mem-worker` | `npm run worker:stop` | Remove worker |
 | `pm2 logs claude-mem-worker` | `npm run worker:logs` | View logs |
 | `pm2 describe claude-mem-worker` | `npm run worker:status` | Detailed status |
@@ -451,7 +451,7 @@ pm2 save  # Persist the deletion
 rm ~/.claude-mem/.pm2-migrated

 # Restart worker
-npm run worker:restart
+claude-mem restart
 ```

 ### Scenario 2: Stale PID File (Process Dead)
@@ -483,7 +483,7 @@ lsof -i :37777
 kill -9 <PID>

 # Restart worker
-npm run worker:restart
+claude-mem restart
 ```

 ### Common Error Messages
@@ -1,497 +1,448 @@
 ---
 title: "Search Architecture"
-description: "MCP tools with 3-layer workflow for token-efficient memory retrieval"
+description: "mem-search skill with HTTP API and progressive disclosure"
 ---

 # Search Architecture

-Claude-mem uses an **MCP-based search architecture** that provides intelligent memory retrieval through 4 streamlined tools following a 3-layer workflow pattern.
+Claude-Mem uses a skill-based search architecture that provides intelligent memory retrieval through natural language queries. This replaced the MCP-based approach in v5.4.0 with a more efficient implementation. The skill was enhanced and renamed to "mem-search" in v5.5.0 for better scope differentiation.

 ## Overview

-**Architecture**: MCP Tools → MCP Protocol → HTTP API → Worker Service
+**Architecture**: Skill-Based Search + HTTP API + Progressive Disclosure

 **Key Components**:
-1. **MCP Tools** (4 tools) - `search`, `timeline`, `get_observations`, `__IMPORTANT`
-2. **MCP Server** (`plugin/scripts/mcp-server.cjs`) - Thin wrapper over HTTP API
-3. **HTTP API Endpoints** - Fast search operations on Worker Service (port 37777)
-4. **Worker Service** - Express.js server with FTS5 full-text search
-5. **SQLite Database** - Persistent storage with FTS5 virtual tables
-6. **Chroma Vector DB** - Semantic search with hybrid retrieval
+1. **mem-search Skill** (`plugin/skills/mem-search/SKILL.md`) - Auto-invoked when users ask about past work
+2. **HTTP API Endpoints** (10 routes) - Fast, efficient search operations on port 37777
+3. **Worker Service** - Express.js server with FTS5 full-text search
+4. **SQLite Database** - Persistent storage with FTS5 virtual tables
+5. **Chroma Vector DB** - Semantic search with hybrid retrieval

-**Token Efficiency**: ~10x savings through 3-layer workflow pattern
+**v5.5.0 Enhancement**: Renamed from "search" to "mem-search" with:
+- Effectiveness increased from 67% to 100%
+- Concrete triggers increased from 44% to 85%
+- 5+ unique identifiers for better scope differentiation
+- Comprehensive documentation (17 files, 12 operation guides)

 ## How It Works

-### 1. User Query
-
-Claude has access to 4 MCP tools. When searching memory, Claude follows the 3-layer workflow:
+### 1. User Query (Natural Language)

 ```
-Step 1: search(query="authentication bug", type="bugfix", limit=10)
-Step 2: timeline(anchor=<observation_id>, depth_before=3, depth_after=3)
-Step 3: get_observations(ids=[123, 456, 789])
+User: "What bugs did we fix last session?"
 ```

-### 2. MCP Protocol
+### 2. Skill Invocation

-MCP server receives tool call via JSON-RPC over stdio:
-
-```json
-{
-  "method": "tools/call",
-  "params": {
-    "name": "search",
-    "arguments": {
-      "query": "authentication bug",
-      "type": "bugfix",
-      "limit": 10
-    }
-  }
-}
-```
+Claude recognizes the intent and invokes the mem-search skill:
+- Skill frontmatter (~250 tokens) loaded at session start
+- Full skill instructions loaded on-demand when skill is invoked
+- Progressive disclosure pattern minimizes context overhead
+- "mem-search" naming provides clear scope differentiation from native memory

 ### 3. HTTP API Call

-MCP server translates to HTTP request:
+The skill uses `curl` to call the HTTP API:

-```typescript
-const url = `http://localhost:37777/api/search?query=authentication%20bug&type=bugfix&limit=10`;
-const response = await fetch(url);
+```bash
+curl "http://localhost:37777/api/search/observations?query=bugs&type=bugfix&limit=5"
 ```

-### 4. Worker Processing
+### 4. FTS5 Search

-Worker service executes FTS5 query:
+Worker service queries SQLite FTS5 virtual tables:

 ```sql
 SELECT * FROM observations_fts
 WHERE observations_fts MATCH ?
 AND type = 'bugfix'
 ORDER BY rank
-LIMIT 10
+LIMIT 5
 ```

-### 5. Results Returned
+### 5. Results Formatted

-Worker returns structured data → MCP server → Claude:
+Skill formats results and returns to Claude:

+```
+## Recent Bugfixes
+
+1. [bugfix] Fixed authentication token expiry
+   Date: 2025-11-08 14:23:45
+   Files: src/auth/jwt.ts
+
+2. [bugfix] Resolved database connection leak
+   Date: 2025-11-08 13:15:22
+   Files: src/services/database.ts
+```
+
+### 6. User Sees Answer
+
+Claude presents the formatted results naturally in conversation.
+
+## Architecture Change (v5.4.0)
+
+### Before: MCP-Based Search
+
+**Approach**: 9 MCP tools registered at session start
+
+**Token Cost**: ~2,500 tokens in tool definitions per session
+- Each tool's schema, parameters, descriptions loaded
+- All 9 tools available whether needed or not
+- No progressive disclosure
+
+**Example MCP Tool**:
 ```json
 {
-  "content": [{
-    "type": "text",
-    "text": "| ID | Time | Title | Type |\n|---|---|---|---|\n| #123 | 2:15 PM | Fixed auth token expiry | bugfix |"
-  }]
-}
-```
-
-### 6. Claude Processes Results
-
-Claude reviews the index, decides which observations are relevant, and can:
- Use `timeline` to get context
- Use `get_observations` to fetch full details for selected IDs
-
-## The 4 MCP Tools
-
-### `__IMPORTANT` - Workflow Documentation
-
-Always visible to Claude. Explains the 3-layer workflow pattern.
-
-**Description:**
-```
-3-LAYER WORKFLOW (ALWAYS FOLLOW):
-1. search(query) → Get index with IDs (~50-100 tokens/result)
-2. timeline(anchor=ID) → Get context around interesting results
-3. get_observations([IDs]) → Fetch full details ONLY for filtered IDs
-NEVER fetch full details without filtering first. 10x token savings.
-```
-
-**Purpose:** Ensures Claude follows token-efficient pattern
-
-### `search` - Search Memory Index
-
-**Tool Definition:**
-```typescript
-{
-  name: 'search',
-  description: 'Step 1: Search memory. Returns index with IDs. Params: query, limit, project, type, obs_type, dateStart, dateEnd, offset, orderBy',
-  inputSchema: {
-    type: 'object',
-    properties: {},
-    additionalProperties: true  // Accepts any parameters
-  }
-}
-```
-
-**HTTP Endpoint:** `GET /api/search`
-
-**Parameters:**
- `query` - Full-text search query
- `limit` - Maximum results (default: 20)
- `type` - Filter by observation type
- `project` - Filter by project name
- `dateStart`, `dateEnd` - Date range filters
- `offset` - Pagination offset
- `orderBy` - Sort order
-
-**Returns:** Compact index with IDs, titles, dates, types (~50-100 tokens per result)
-
-### `timeline` - Get Chronological Context
-
-**Tool Definition:**
-```typescript
-{
-  name: 'timeline',
-  description: 'Step 2: Get context around results. Params: anchor (observation ID) OR query (finds anchor automatically), depth_before, depth_after, project',
-  inputSchema: {
-    type: 'object',
-    properties: {},
-    additionalProperties: true
-  }
-}
-```
-
-**HTTP Endpoint:** `GET /api/timeline`
-
-**Parameters:**
- `anchor` - Observation ID to center timeline around (optional if query provided)
- `query` - Search query to find anchor automatically (optional if anchor provided)
- `depth_before` - Number of observations before anchor (default: 3)
- `depth_after` - Number of observations after anchor (default: 3)
- `project` - Filter by project name
-
-**Returns:** Chronological view showing what happened before/during/after
-
-### `get_observations` - Fetch Full Details
-
-**Tool Definition:**
-```typescript
-{
-  name: 'get_observations',
-  description: 'Step 3: Fetch full details for filtered IDs. Params: ids (array of observation IDs, required), orderBy, limit, project',
-  inputSchema: {
-    type: 'object',
-    properties: {
-      ids: {
-        type: 'array',
-        items: { type: 'number' },
-        description: 'Array of observation IDs to fetch (required)'
-      }
-    },
-    required: ['ids'],
-    additionalProperties: true
-  }
-}
-```
-
-**HTTP Endpoint:** `POST /api/observations/batch`
-
-**Body:**
-```json
-{
-  "ids": [123, 456, 789],
-  "orderBy": "date_desc",
-  "project": "my-app"
-}
-```
-
-**Returns:** Complete observation details (~500-1,000 tokens per observation)
-
-## MCP Server Implementation
-
-**Location:** `/Users/YOUR_USERNAME/.claude/plugins/marketplaces/thedotmack/plugin/scripts/mcp-server.cjs`
-
-**Role:** Thin wrapper that translates MCP protocol to HTTP API calls
-
-**Key Characteristics:**
- ~312 lines of code (reduced from ~2,718 lines in old implementation)
- No business logic - just protocol translation
- Single source of truth: Worker HTTP API
- Simple schemas with `additionalProperties: true`
-
-**Handler Example:**
-```typescript
-{
-  name: 'search',
-  handler: async (args: any) => {
-    const endpoint = '/api/search';
-    const searchParams = new URLSearchParams();
-
-    for (const [key, value] of Object.entries(args)) {
-      searchParams.append(key, String(value));
+  "name": "search_observations",
+  "description": "Full-text search across observations...",
+  "inputSchema": {
+    "type": "object",
+    "properties": {
+      "query": { "type": "string", "description": "..." },
+      "type": { "type": "array", "items": { "enum": [...] } },
+      "format": { "enum": ["index", "full"] },
+      // ... many more parameters
    }
-
-    const url = `http://localhost:37777${endpoint}?${searchParams}`;
-    const response = await fetch(url);
-    return await response.json();
  }
 }
 ```

-## Worker HTTP API
+### After: Skill-Based Search

-**Location:** `src/services/worker-service.ts`
+**Approach**: 1 mem-search skill with progressive disclosure

-**Port:** 37777
+**Token Cost**: ~250 tokens in skill frontmatter per session
+- Only skill description loaded at session start
+- Full instructions loaded on-demand when skill is invoked
+- HTTP API endpoints instead of MCP protocol

-**Search Endpoints:**
-```typescript
-GET  /api/search           # Main search (used by MCP search tool)
-GET  /api/timeline         # Timeline context (used by MCP timeline tool)
-POST /api/observations/batch  # Fetch by IDs (used by MCP get_observations tool)
-GET  /api/health           # Health check
+**Example Skill Frontmatter**:
+```markdown
+# Claude-Mem mem-search Skill
+
+Access claude-mem's persistent memory through a comprehensive HTTP API.
+Search for past work, understand context, and learn from previous decisions.
+
+## When to Use This Skill
+
+Invoke this skill when users ask about:
+- Past work: "What did we do last session?"
+- Bug fixes: "Did we fix this before?"
+- Features: "How did we implement authentication?"
+...
 ```

-**Database Access:**
+**Token Efficiency**: Minimal frontmatter at session start with progressive disclosure
+
+## HTTP API Endpoints
+
+The worker service exposes 10 search endpoints:
+
+### Full-Text Search
+
+```
+GET /api/search/observations
+GET /api/search/sessions
+GET /api/search/prompts
+```
+
+**Parameters**:
+- `query` - FTS5 search query (required)
+- `type` - Filter by type (bugfix, feature, refactor, etc.)
+- `project` - Filter by project name
+- `limit` - Maximum results (default: 20)
+- `offset` - Pagination offset
+- `format` - Response format (index or full)
+
+**Example**:
+```bash
+curl "http://localhost:37777/api/search/observations?query=authentication&type=decision&limit=5"
+```
+
+### Filtered Search
+
+```
+GET /api/search/by-type
+GET /api/search/by-concept
+GET /api/search/by-file
+```
+
+**Parameters**:
+- `type` / `concept` / `filePath` - Filter criteria (required)
+- `project` - Filter by project
+- `limit` - Maximum results
+- `format` - Response format
+
+**Example**:
+```bash
+curl "http://localhost:37777/api/search/by-file?filePath=worker-service.ts&limit=10"
+```
+
+### Context Retrieval
+
+```
+GET /api/context/recent
+GET /api/context/timeline
+GET /api/timeline/by-query
+```
+
+**Parameters**:
+- `project` - Filter by project
+- `limit` - Number of sessions/records
+- `anchor` - Timeline anchor point (ID or timestamp)
+- `depth_before` - Records before anchor
+- `depth_after` - Records after anchor
+
+**Example**:
+```bash
+curl "http://localhost:37777/api/context/recent?project=claude-mem&limit=5"
+```
+
+### Documentation
+
+```
+GET /api/search/help
+```
+
+Returns API documentation in JSON format.
+
+## Progressive Disclosure Pattern
+
+The mem-search skill uses progressive disclosure to minimize token usage:
+
+### Layer 1: Skill Frontmatter (Session Start)
+
+**What's Loaded**: Skill description and when to use it (~250 tokens)
+
+**Purpose**: Claude can recognize when to invoke the skill
+
+**Example**:
+```markdown
+# Claude-Mem mem-search Skill
+
+Access claude-mem's persistent memory through a comprehensive HTTP API.
+
+## When to Use This Skill
+Invoke this skill when users ask about:
+- Past work: "What did we do last session?"
+- Bug fixes: "Did we fix this before?"
+...
+```
+
+### Layer 2: Full Skill Instructions (On-Demand)
+
+**What's Loaded**: Complete operation documentation (~2,500 tokens)
+
+**Purpose**: Detailed instructions for each search operation
+
+**When Loaded**: Only when Claude invokes the skill
+
+**Example Structure**:
+```
+/skills/search/
+├── SKILL.md (main frontmatter)
+├── operations/
+│   ├── observations.md (detailed instructions)
+│   ├── sessions.md
+│   ├── prompts.md
+│   ├── by-type.md
+│   ├── by-concept.md
+│   ├── by-file.md
+│   ├── recent-context.md
+│   ├── timeline.md
+│   ├── timeline-by-query.md
+│   ├── help.md
+│   ├── formatting.md
+│   └── common-workflows.md
+```
+
+### Layer 3: API Response
+
+**What's Returned**: Search results in requested format
+
+**Format Options**:
+- `index` - Titles, dates, IDs only (~50-100 tokens per result)
+- `full` - Complete details (~500-1000 tokens per result)
+
+**Progressive Usage**: Start with `index`, drill down with `full` as needed
+
+## Implementation Details
+
+### mem-search Skill Structure
+
+```
+plugin/skills/mem-search/
+├── SKILL.md                           # Main frontmatter (~250 tokens)
+├── operations/
+│   ├── observations.md                # Search observations
+│   ├── sessions.md                    # Search sessions
+│   ├── prompts.md                     # Search prompts
+│   ├── by-type.md                     # Filter by type
+│   ├── by-concept.md                  # Filter by concept
+│   ├── by-file.md                     # Filter by file
+│   ├── recent-context.md              # Get recent context
+│   ├── timeline.md                    # Timeline around point
+│   ├── timeline-by-query.md           # Search + timeline
+│   ├── help.md                        # API documentation
+│   ├── formatting.md                  # Result formatting guide
+│   └── common-workflows.md            # Usage patterns
+```
+
+### Worker Service Integration
+
+**File**: `src/services/worker-service.ts`
+
+**Search Routes**:
+```typescript
+// Full-text search
+app.get('/api/search/observations', handleSearchObservations);
+app.get('/api/search/sessions', handleSearchSessions);
+app.get('/api/search/prompts', handleSearchPrompts);
+
+// Filtered search
+app.get('/api/search/by-type', handleSearchByType);
+app.get('/api/search/by-concept', handleSearchByConcept);
+app.get('/api/search/by-file', handleSearchByFile);
+
+// Context retrieval
+app.get('/api/context/recent', handleRecentContext);
+app.get('/api/context/timeline', handleTimeline);
+app.get('/api/timeline/by-query', handleTimelineByQuery);
+
+// Documentation
+app.get('/api/search/help', handleHelp);
+```
+
+**Database Access**:
 - Uses `SessionSearch` service for FTS5 queries
 - Uses `SessionStore` for structured queries
 - Hybrid search with ChromaDB for semantic similarity

-**FTS5 Full-Text Search:**
-```typescript
-// search tool → HTTP GET → FTS5 query
-SELECT * FROM observations_fts
-WHERE observations_fts MATCH ?
-AND type = ?
-AND date >= ? AND date <= ?
-ORDER BY rank
-LIMIT ? OFFSET ?
-```
-
-## The 3-Layer Workflow Pattern
-
-### Design Philosophy
-
-The 3-layer workflow embodies **progressive disclosure** - a core principle of claude-mem's architecture.
-
-**Layer 1: Index (Search)**
- **What:** Compact table with IDs, titles, dates, types
- **Cost:** ~50-100 tokens per result
- **Purpose:** Survey what exists before committing tokens
- **Decision Point:** "Which observations are relevant?"
-
-**Layer 2: Context (Timeline)**
- **What:** Chronological view of observations around a point
- **Cost:** Variable based on depth
- **Purpose:** Understand narrative arc, see what led to/from a point
- **Decision Point:** "Do I need full details?"
-
-**Layer 3: Details (Get Observations)**
- **What:** Complete observation data (narrative, facts, files, concepts)
- **Cost:** ~500-1,000 tokens per observation
- **Purpose:** Deep dive on validated, relevant observations
- **Decision Point:** "Apply knowledge to current task"
-
-### Token Efficiency
-
-**Traditional RAG Approach:**
-```
-Fetch 20 observations upfront: 10,000-20,000 tokens
-Relevance: ~10% (only 2 observations actually useful)
-Waste: 18,000 tokens on irrelevant context
-```
-
-**3-Layer Workflow:**
-```
-Step 1: search (20 results)        ~1,000-2,000 tokens
-Step 2: Review index, filter to 3 relevant IDs
-Step 3: get_observations (3 IDs)   ~1,500-3,000 tokens
-Total: 2,500-5,000 tokens (50-75% savings)
-```
-
-**10x Savings:** By filtering at index level before fetching full details
-
-## Architecture Evolution
-
-### Before: Complex MCP Implementation
-
-**Approach:** 9 MCP tools with detailed parameter schemas
-
-**Token Cost:** ~2,500 tokens in tool definitions per session
- `search_observations` - Full-text search
- `find_by_type` - Filter by type
- `find_by_file` - Filter by file
- `find_by_concept` - Filter by concept
- `get_recent_context` - Recent sessions
- `get_observation` - Fetch single observation
- `get_session` - Fetch session
- `get_prompt` - Fetch prompt
- `help` - API documentation
-
-**Problems:**
- Overlapping operations (search_observations vs find_by_type)
- Complex parameter schemas
- No built-in workflow guidance
- High token cost at session start
-
-**Code Size:** ~2,718 lines in mcp-server.ts
-
-### After: Streamlined MCP Implementation
-
-**Approach:** 4 MCP tools following 3-layer workflow
-
-**Token Cost:** ~312 lines of code, simplified tool definitions
-
-**Tools:**
-1. `__IMPORTANT` - Workflow guidance (always visible)
-2. `search` - Step 1 (index)
-3. `timeline` - Step 2 (context)
-4. `get_observations` - Step 3 (details)
-
-**Benefits:**
- Progressive disclosure built into tool design
- No overlapping operations
- Simple schemas (`additionalProperties: true`)
- Clear workflow pattern
- ~10x token savings
-
-**Code Size:** ~312 lines in mcp-server.ts (88% reduction)
-
-### Key Insight
-
-**Before:** Progressive disclosure was something Claude had to remember
-
-**After:** Progressive disclosure is enforced by tool design itself
-
-The 3-layer workflow pattern makes it structurally difficult to waste tokens:
- Can't fetch details without first getting IDs from search
- Can't search without seeing workflow reminder (`__IMPORTANT`)
- Timeline provides middle ground between index and full details
-
-## Configuration
-
-### Claude Desktop
-
-Add to `claude_desktop_config.json`:
-
-```json
-{
-  "mcpServers": {
-    "mcp-search": {
-      "command": "node",
-      "args": [
-        "/Users/YOUR_USERNAME/.claude/plugins/marketplaces/thedotmack/plugin/scripts/mcp-server.cjs"
-      ]
-    }
-  }
-}
-```
-
-### Claude Code
-
-MCP server is automatically configured via plugin installation. No manual setup required.
-
-**Both clients use the same MCP tools** - the architecture works identically for Claude Desktop and Claude Code.
-
-## Security
-
-### FTS5 Injection Prevention
-
-All search queries are escaped before FTS5 processing:
+### Security

+**FTS5 Injection Prevention** (v4.2.3):
 ```typescript
 function escapeFTS5Query(query: string): string {
  return query.replace(/"/g, '""');
 }
 ```

-**Testing:** 332 injection attack tests covering special characters, SQL keywords, quote escaping, and boolean operators.
+All user-provided search queries are properly escaped to prevent SQL injection.

-### MCP Protocol Security
+**Comprehensive Testing**: 332 injection attack tests covering:
+- Special characters
+- SQL keywords
+- Quote escaping
+- Boolean operators

- Stdio transport (no network exposure)
- Local-only HTTP API (localhost:37777)
- No authentication needed (local development only)
+## Benefits

-## Performance
+### 1. Token Efficiency

-**FTS5 Full-Text Search:** Sub-10ms for typical queries
+**Before (MCP)**:
+- Session start: All tool definitions loaded upfront
+- Every session pays this cost
+- No progressive disclosure

-**MCP Overhead:** Minimal - simple protocol translation
+**After (Skill)**:
+- Session start: Minimal token cost for skill frontmatter
+- Full instructions loaded only when invoked (progressive disclosure)
+- More efficient than loading all tool definitions upfront

-**Caching:** HTTP layer allows response caching (future enhancement)
+### 2. Natural Language Interface

-**Pagination:** Efficient with offset/limit
+**Before**: Users needed to learn MCP tool syntax
+```
+search_observations with query="authentication" and type="decision"
+```

-**Batching:** `get_observations` accepts multiple IDs in single call
+**After**: Users ask naturally
+```
+"What decisions did we make about authentication?"
+```

-## Benefits Over Alternative Approaches
+Claude translates to appropriate API call.

-### vs. Traditional RAG
+### 3. Flexibility

-**Traditional RAG:**
- Fetches everything upfront
- High token cost
- Low relevance ratio
+**HTTP API Benefits**:
+- Can be called from skills, MCP tools, or other clients
+- Easy to test with curl
+- Standard REST conventions
+- JSON responses

-**3-Layer MCP:**
- Fetches only what's needed
- ~10x token savings
- 100% relevance (Claude chooses what to fetch)
+**Progressive Disclosure**:
+- Loads only what's needed
+- Can add more operations without increasing base cost
+- Documentation co-located with operations

-### vs. Previous MCP Implementation (v5.x)
+### 4. Performance

-**Previous (9 tools):**
- Complex schemas
- Overlapping operations
- No workflow guidance
- ~2,500 tokens in definitions
+**Fast Queries**: FTS5 full-text search under 10ms for typical queries

-**Current (4 tools):**
- Simple schemas
- Clear workflow
- Built-in guidance
- ~312 lines of code
+**Caching**: HTTP layer allows response caching

-### vs. Skill-Based Approach (Previously)
+**Pagination**: Efficient result pagination with offset/limit

-**Skill approach:**
- Required separate skill files
- HTTP API called directly via curl
- Progressive disclosure through skill loading
+## Migration Notes

-**MCP approach:**
- Native MCP protocol (better Claude integration)
- Cleaner architecture (protocol translation layer)
- Works with both Claude Desktop and Claude Code
- Simpler to maintain (no skill files)
+### For Users

-**Migration:** Skill-based search was removed in favor of streamlined MCP architecture.
+**No Action Required**: The migration from MCP to skill-based search is transparent.
+
+**Same Questions Work**: Natural language queries work exactly the same way.
+
+**Invisible Change**: Users won't notice any difference except better performance.
+
+### For Developers
+
+**Renamed**: MCP server (formerly `search-server.ts`, now `src/servers/mcp-server.ts`)
+- Source file kept for reference
+- No longer built or registered
+- MCP configuration removed from `plugin/.mcp.json`
+
+**New Implementation**: Skill-based search
+- Skill files: `plugin/skills/mem-search/`
+- HTTP endpoints: `src/services/worker-service.ts` (lines 200-400)
+- Build script: `npm run build` includes skill files
+- Sync script: `npm run sync-marketplace` copies to plugin directory

 ## Troubleshooting

-### MCP Server Not Connected
-
-**Symptoms:** Tools not appearing in Claude
-
-**Solution:**
-1. Check MCP server path in configuration
-2. Verify worker service is running: `curl http://localhost:37777/api/health`
-3. Restart Claude Desktop/Code
-
 ### Worker Service Not Running

-**Symptoms:** MCP tools fail with connection errors
+If searches fail, check worker service:

-**Solution:**
 ```bash
 npm run worker:status       # Check status
-npm run worker:restart      # Restart worker
+claude-mem restart      # Restart worker
 npm run worker:logs         # View logs
 ```

-### Empty Search Results
+### HTTP Endpoints Not Responding

-**Symptoms:** search() returns no results
+Test endpoints directly:

-**Troubleshooting:**
-1. Test API directly: `curl "http://localhost:37777/api/search?query=test"`
-2. Check database: `ls ~/.claude-mem/claude-mem.db`
-3. Verify observations exist: `curl "http://localhost:37777/api/health"`
+```bash
+# Health check
+curl http://localhost:37777/health
+
+# Search test
+curl "http://localhost:37777/api/search/observations?query=test&limit=1"
+```
+
+### Skill Not Invoking
+
+If Claude doesn't invoke the mem-search skill automatically:
+
+1. Check skill files exist: `ls ~/.claude/plugins/marketplaces/thedotmack/plugin/skills/mem-search/`
+2. Restart Claude Code session to reload skill definitions
+3. Try more explicit phrasing: "Search past sessions for bug fixes" or "What did we do in yesterday's session?"
+4. Ensure your question is about previous sessions (not current conversation context)

 ## Next Steps

- [Memory Search Usage](/usage/search-tools) - User guide with examples
- [Progressive Disclosure](/progressive-disclosure) - Philosophy behind 3-layer workflow
+- [Search Tools Usage](/usage/search-tools) - User guide with examples
 - [Worker Service Architecture](/architecture/worker-service) - HTTP API details
 - [Database Schema](/architecture/database) - FTS5 tables and indexes
@@ -597,7 +597,7 @@ npm run worker:start
 npm run worker:stop

 # Restart worker
-npm run worker:restart
+claude-mem restart

 # View logs
 npm run worker:logs
@@ -14,11 +14,10 @@ Settings are managed in `~/.claude-mem/settings.json`. The file is auto-created
 | Setting                       | Default                         | Description                           |
 |-------------------------------|---------------------------------|---------------------------------------|
 | `CLAUDE_MEM_MODEL`            | `sonnet`                        | AI model for processing observations (when using Claude) |
-| `CLAUDE_MEM_PROVIDER`         | `claude`                        | AI provider: `claude`, `gemini`, or `openrouter` |
+| `CLAUDE_MEM_PROVIDER`         | `claude`                        | AI provider: `claude` or `gemini` |
 | `CLAUDE_MEM_MODE`             | `code`                          | Active mode profile (e.g., `code--es`, `email-investigation`) |
 | `CLAUDE_MEM_CONTEXT_OBSERVATIONS` | `50`                        | Number of observations to inject      |
 | `CLAUDE_MEM_WORKER_PORT`      | `37777`                         | Worker service port                   |
-| `CLAUDE_MEM_WORKER_HOST`      | `127.0.0.1`                     | Worker service host address           |
 | `CLAUDE_MEM_SKIP_TOOLS`       | `ListMcpResourcesTool,SlashCommand,Skill,TodoWrite,AskUserQuestion` | Comma-separated tools to exclude from observations |

 ### Gemini Provider Settings
@@ -26,23 +25,10 @@ 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-preview` |
+| `CLAUDE_MEM_GEMINI_MODEL`     | `gemini-2.5-flash-lite`          | Gemini model: `gemini-2.5-flash-lite`, `gemini-2.5-flash`, `gemini-3-flash` |

 See [Gemini Provider](usage/gemini-provider) for detailed configuration and free tier information.

-### OpenRouter Provider Settings
-
-| Setting                                      | Default                     | Description                           |
-|----------------------------------------------|-----------------------------|---------------------------------------|
-| `CLAUDE_MEM_OPENROUTER_API_KEY`              | —                           | OpenRouter API key ([get key](https://openrouter.ai/keys)) |
-| `CLAUDE_MEM_OPENROUTER_MODEL`                | `xiaomi/mimo-v2-flash:free` | Model identifier (supports 100+ models) |
-| `CLAUDE_MEM_OPENROUTER_MAX_CONTEXT_MESSAGES` | `20`                        | Max messages in conversation history  |
-| `CLAUDE_MEM_OPENROUTER_MAX_TOKENS`           | `100000`                    | Token budget safety limit             |
-| `CLAUDE_MEM_OPENROUTER_SITE_URL`             | —                           | Optional: URL for analytics           |
-| `CLAUDE_MEM_OPENROUTER_APP_NAME`             | `claude-mem`                | Optional: App name for analytics      |
-
-See [OpenRouter Provider](usage/openrouter-provider) for detailed configuration, free model list, and usage guide.
-
 ### System Configuration

 | Setting                       | Default                         | Description                           |
@@ -190,16 +176,19 @@ Hooks are configured in `plugin/hooks/hooks.json`:
 }
 ```

-### Search Configuration
+### Search Configuration (v5.4.0+)

-Claude-Mem provides MCP search tools for querying your project history.
+**Migration Note**: As of v5.4.0, Claude-Mem uses skill-based search instead of MCP tools. As of v5.5.0, the skill was renamed to "mem-search" for better scope differentiation.

-**No configuration required** - MCP tools are automatically available in Claude Code sessions.
+**Previous (v5.3.x and earlier)**: MCP search server with 9 tools (~2,500 tokens per session)
+**Current (v5.4.0+)**: mem-search skill with HTTP API (~250 tokens per session)

-Search operations are provided via:
- **MCP Server**: 3 tools (search, timeline, get_observations) with progressive disclosure
+**No configuration required** - the mem-search skill is automatically available in Claude Code sessions.
+
+Search operations are now provided via:
+- **Skill**: `plugin/skills/mem-search/SKILL.md` (auto-invoked when users ask about past work)
 - **HTTP API**: 10 endpoints on worker service port 37777
- **Auto-Invocation**: Claude recognizes natural language queries about past work
+- **Progressive Disclosure**: Full instructions loaded on-demand only when needed

 ## Version Channel

@@ -227,16 +216,6 @@ Endless Mode is experimental and slower than standard mode. See [Beta Features](

 Worker service is managed by Bun as a background process. The worker auto-starts on first session and runs continuously in the background.

-## Folder Context Files
-
-Claude-mem can automatically generate `CLAUDE.md` files in your project folders with activity timelines. This feature is disabled by default.
-
-| Setting | Default | Description |
-|---------|---------|-------------|
-| `CLAUDE_MEM_FOLDER_CLAUDEMD_ENABLED` | `false` | Enable auto-generation of folder CLAUDE.md files |
-
-See [Folder Context Files](usage/folder-context) for full documentation on how this feature works, configuration options, and git integration recommendations.
-
 ## Context Injection Configuration

 Claude-Mem injects past observations into each new session, giving Claude awareness of recent work. You can configure exactly what gets injected using the **Context Settings Modal**.
@@ -366,7 +345,7 @@ Edit `~/.claude-mem/settings.json`:

 Then restart the worker:
 ```bash
-npm run worker:restart
+claude-mem restart
 ```

 ### Custom Model
@@ -381,7 +360,7 @@ Edit `~/.claude-mem/settings.json`:
 Then restart the worker:
 ```bash
 export CLAUDE_MEM_MODEL=opus
-npm run worker:restart
+claude-mem restart
 ```

 ### Custom Skip Tools
@@ -438,7 +417,7 @@ Enable debug logging:

 ```bash
 export DEBUG=claude-mem:*
-npm run worker:restart
+claude-mem restart
 npm run worker:logs
 ```

@@ -456,7 +435,7 @@ npm run worker:logs

 1. Restart worker after changes:
   ```bash
-   npm run worker:restart
+   claude-mem restart
   ```

 2. Verify environment variables:
@@ -490,7 +469,7 @@ If port 37777 is already in use:

 2. Restart worker:
   ```bash
-   npm run worker:restart
+   claude-mem restart
   ```

 3. Verify new port:
@@ -1,191 +0,0 @@
---
-title: "Cursor + Gemini Setup"
-description: "Use Claude-Mem in Cursor with Google's free Gemini API"
---
-
-# Cursor + Gemini Setup
-
-This guide walks you through setting up Claude-Mem in Cursor using Google's Gemini API. Gemini offers a generous free tier that handles typical individual usage.
-
-<Info>
-**Free Tier:** 1,500 requests per day with `gemini-2.5-flash-lite`. No credit card required.
-</Info>
-
-## Step 1: Get a Gemini API Key
-
-1. Go to [Google AI Studio](https://aistudio.google.com/apikey)
-2. Sign in with your Google account
-3. Accept the Terms of Service
-4. Click **Create API key**
-5. Choose or create a Google Cloud project
-6. Copy your API key - you'll need it in Step 3
-
-<Tip>
-**Higher rate limits:** Enable billing on your Google Cloud project to unlock 4,000 RPM (vs 10 RPM without billing). You won't be charged unless you exceed the free quota.
-</Tip>
-
-## Step 2: Clone and Build Claude-Mem
-
-```bash
-# Clone the repository
-git clone https://github.com/thedotmack/claude-mem.git
-cd claude-mem
-
-# Install dependencies
-bun install
-
-# Build the project
-bun run build
-```
-
-## Step 3: Configure Gemini Provider
-
-### Option A: Interactive Setup (Recommended)
-
-Run the setup wizard which guides you through everything:
-
-```bash
-bun run cursor:setup
-```
-
-The wizard will:
-1. Detect you don't have Claude Code
-2. Ask you to choose Gemini as your provider
-3. Prompt for your API key
-4. Install hooks automatically
-5. Start the worker
-
-### Option B: Manual Configuration
-
-Create the settings file manually:
-
-```bash
-# Create settings directory
-mkdir -p ~/.claude-mem
-
-# Create settings file with Gemini configuration
-cat > ~/.claude-mem/settings.json << 'EOF'
-{
-  "CLAUDE_MEM_PROVIDER": "gemini",
-  "CLAUDE_MEM_GEMINI_API_KEY": "YOUR_GEMINI_API_KEY"
-}
-EOF
-```
-
-Replace `YOUR_GEMINI_API_KEY` with your actual API key.
-
-Then install hooks and start the worker:
-
-```bash
-bun run cursor:install
-bun run worker:start
-```
-
-## Step 4: Restart Cursor
-
-Close and reopen Cursor IDE for the hooks to take effect.
-
-## Step 5: Verify Installation
-
-```bash
-# Check worker is running
-bun run worker:status
-
-# Check hooks are installed
-bun run cursor:status
-```
-
-Open http://localhost:37777 to see the memory viewer.
-
-## Available Gemini Models
-
-| Model | Free Tier RPM | Notes |
-|-------|---------------|-------|
-| `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-preview` | 5 (1,000 with billing) | Latest model |
-
-To change the model, update your settings:
-
-```json
-{
-  "CLAUDE_MEM_PROVIDER": "gemini",
-  "CLAUDE_MEM_GEMINI_API_KEY": "your-key",
-  "CLAUDE_MEM_GEMINI_MODEL": "gemini-2.5-flash"
-}
-```
-
-## Rate Limiting
-
-Claude-mem automatically handles rate limiting for free tier usage:
-
- Requests are spaced to stay within limits
- Processing may be slightly slower but stays within quota
- No errors or lost observations
-
-**To remove rate limiting:** Enable billing on your Google Cloud project, then add to settings:
-
-```json
-{
-  "CLAUDE_MEM_GEMINI_BILLING_ENABLED": true
-}
-```
-
-You'll still use the free quota but with much higher rate limits.
-
-## Troubleshooting
-
-### "Gemini API key not configured"
-
-Ensure your settings file exists and has the correct format:
-
-```bash
-cat ~/.claude-mem/settings.json
-```
-
-Should output something like:
-```json
-{
-  "CLAUDE_MEM_PROVIDER": "gemini",
-  "CLAUDE_MEM_GEMINI_API_KEY": "AIza..."
-}
-```
-
-### Rate limit errors (HTTP 429)
-
-You're exceeding the free tier limits. Options:
-1. Wait a few minutes for the rate limit to reset
-2. Enable billing on Google Cloud to unlock higher limits
-3. Switch to OpenRouter for higher volume needs
-
-### API key invalid
-
-1. Verify your key at [Google AI Studio](https://aistudio.google.com/apikey)
-2. Ensure there are no extra spaces or newlines in your settings.json
-3. Try generating a new API key
-
-### Worker not processing observations
-
-Check the worker logs:
-
-```bash
-bun run worker:logs
-```
-
-Look for error messages related to Gemini API calls.
-
-## Switching Providers Later
-
-You can switch between Gemini, OpenRouter, and Claude SDK at any time by updating your settings. No restart required - changes take effect on the next observation.
-
-```json
-{
-  "CLAUDE_MEM_PROVIDER": "openrouter"
-}
-```
-
-## Next Steps
-
- [Cursor Integration Overview](/cursor/index) - All Cursor features
- [OpenRouter Setup](/cursor/openrouter-setup) - Alternative provider with 100+ models
- [Configuration Reference](../configuration) - All settings options
@@ -1,180 +0,0 @@
---
-title: "Cursor Integration"
-description: "Persistent AI memory for Cursor IDE - free tier options available"
---
-
-# Cursor Integration
-
-> **Your AI stops forgetting. Give Cursor persistent memory.**
-
-Every Cursor session starts fresh - your AI doesn't remember what it worked on yesterday. Claude-mem changes that. Your agent builds cumulative knowledge about your codebase, decisions, and patterns over time.
-
-<CardGroup cols={2}>
-  <Card title="Free to Start" icon="dollar-sign">
-    Works with Gemini's free tier (1500 req/day) - no subscription required
-  </Card>
-  <Card title="Automatic Capture" icon="bolt">
-    MCP tools, shell commands, and file edits logged without effort
-  </Card>
-  <Card title="Smart Context" icon="brain">
-    Relevant history injected into every chat session
-  </Card>
-  <Card title="Works Everywhere" icon="check">
-    With or without Claude Code subscription
-  </Card>
-</CardGroup>
-
-<Info>
-**No Claude Code subscription required.** Use Gemini (free tier) or OpenRouter as your AI provider.
-</Info>
-
-## How It Works
-
-Claude-mem integrates with Cursor through native hooks:
-
-1. **Session hooks** capture tool usage, file edits, and shell commands
-2. **AI extraction** compresses observations into semantic summaries
-3. **Context injection** loads relevant history into each new session
-4. **Memory viewer** at http://localhost:37777 shows your knowledge base
-
-## Installation Paths
-
-Choose the installation method that fits your setup:
-
-### Path A: Cursor-Only Users (No Claude Code)
-
-If you're using Cursor without a Claude Code subscription:
-
-```bash
-# Clone and build
-git clone https://github.com/thedotmack/claude-mem.git
-cd claude-mem && bun install && bun run build
-
-# Run interactive setup wizard
-bun run cursor:setup
-```
-
-The setup wizard will:
- Detect you don't have Claude Code
- Help you choose and configure a free AI provider (Gemini recommended)
- Install hooks automatically
- Start the worker service
-
-**Detailed guides:**
- [Gemini Setup](/cursor/gemini-setup) - Recommended free option (1500 req/day)
- [OpenRouter Setup](/cursor/openrouter-setup) - 100+ models including free options
-
-### Path B: Claude Code Users
-
-If you have Claude Code installed:
-
-```bash
-# Install the plugin (if not already)
-/plugin marketplace add thedotmack/claude-mem
-/plugin install claude-mem
-
-# Install Cursor hooks
-claude-mem cursor install
-```
-
-The plugin uses Claude's SDK by default but you can switch to Gemini or OpenRouter anytime.
-
-## Prerequisites
-
-<AccordionGroup>
-  <Accordion title="macOS">
-    - [Bun](https://bun.sh): `curl -fsSL https://bun.sh/install | bash`
-    - Cursor IDE
-    - jq and curl: `brew install jq curl`
-  </Accordion>
-  <Accordion title="Linux">
-    - [Bun](https://bun.sh): `curl -fsSL https://bun.sh/install | bash`
-    - Cursor IDE
-    - jq and curl: `apt install jq curl` or `dnf install jq curl`
-  </Accordion>
-  <Accordion title="Windows">
-    - [Bun](https://bun.sh): `powershell -c "irm bun.sh/install.ps1 | iex"`
-    - Cursor IDE
-    - PowerShell 5.1+ (included in Windows 10/11)
-    - Git for Windows
-  </Accordion>
-</AccordionGroup>
-
-## Quick Commands Reference
-
-After installation, these commands are available from the claude-mem directory:
-
-| Command | Description |
-|---------|-------------|
-| `bun run cursor:setup` | Interactive setup wizard |
-| `bun run cursor:install` | Install Cursor hooks |
-| `bun run cursor:uninstall` | Remove Cursor hooks |
-| `bun run cursor:status` | Check hook installation status |
-| `bun run worker:start` | Start the worker service |
-| `bun run worker:stop` | Stop the worker service |
-| `bun run worker:status` | Check worker status |
-
-## Verifying Installation
-
-After setup, verify everything is working:
-
-1. **Check worker status:**
-   ```bash
-   bun run worker:status
-   ```
-
-2. **Check hook installation:**
-   ```bash
-   bun run cursor:status
-   ```
-
-3. **Open the memory viewer:**
-   Open http://localhost:37777 in your browser
-
-4. **Restart Cursor** and start a coding session - you should see context being captured
-
-## Provider Comparison
-
-| Provider | Cost | Rate Limit | Best For |
-|----------|------|------------|----------|
-| Gemini | Free tier | 1500 req/day | Individual use, getting started |
-| OpenRouter | Pay-per-use + free models | Varies by model | Model variety, high volume |
-| Claude SDK | Included with Claude Code | Unlimited | Claude Code subscribers |
-
-<Tip>
-**Recommendation:** Start with Gemini's free tier. It handles typical individual usage well. Switch to OpenRouter or Claude SDK if you need higher limits.
-</Tip>
-
-## Troubleshooting
-
-### Worker not starting
-
-```bash
-# Check if port is in use
-lsof -i :37777
-
-# Force restart
-bun run worker:stop && bun run worker:start
-
-# Check logs
-bun run worker:logs
-```
-
-### Hooks not firing
-
-1. Restart Cursor IDE after installation
-2. Check hooks are installed: `bun run cursor:status`
-3. Verify hooks.json exists in `.cursor/` directory
-
-### No context appearing
-
-1. Ensure worker is running: `bun run worker:status`
-2. Check that you have observations: visit http://localhost:37777
-3. Verify your API key is configured correctly
-
-## Next Steps
-
- [Gemini Setup Guide](/cursor/gemini-setup) - Detailed free tier setup
- [OpenRouter Setup Guide](/cursor/openrouter-setup) - Configure OpenRouter
- [Configuration Reference](../configuration) - All settings options
- [Troubleshooting](../troubleshooting) - Common issues and solutions
@@ -1,191 +0,0 @@
---
-title: "Cursor + OpenRouter Setup"
-description: "Use Claude-Mem in Cursor with OpenRouter's 100+ AI models"
---
-
-# Cursor + OpenRouter Setup
-
-This guide walks you through setting up Claude-Mem in Cursor using OpenRouter. OpenRouter provides access to 100+ AI models from various providers, including several free options.
-
-<Info>
-**Model variety:** Access Claude, GPT-4, Gemini, Llama, Mistral, and many more through a single API key.
-</Info>
-
-## Step 1: Get an OpenRouter API Key
-
-1. Go to [OpenRouter](https://openrouter.ai)
-2. Sign up or sign in
-3. Navigate to [API Keys](https://openrouter.ai/keys)
-4. Click **Create Key**
-5. Copy your API key - you'll need it in Step 3
-
-<Tip>
-**Free models available:** OpenRouter offers free versions of several models including Gemini Flash and others. Check the [model list](https://openrouter.ai/models?show_free=true) for current free options.
-</Tip>
-
-## Step 2: Clone and Build Claude-Mem
-
-```bash
-# Clone the repository
-git clone https://github.com/thedotmack/claude-mem.git
-cd claude-mem
-
-# Install dependencies
-bun install
-
-# Build the project
-bun run build
-```
-
-## Step 3: Configure OpenRouter Provider
-
-### Option A: Interactive Setup (Recommended)
-
-Run the setup wizard which guides you through everything:
-
-```bash
-bun run cursor:setup
-```
-
-When prompted for provider, select **OpenRouter**.
-
-### Option B: Manual Configuration
-
-Create the settings file manually:
-
-```bash
-# Create settings directory
-mkdir -p ~/.claude-mem
-
-# Create settings file with OpenRouter configuration
-cat > ~/.claude-mem/settings.json << 'EOF'
-{
-  "CLAUDE_MEM_PROVIDER": "openrouter",
-  "CLAUDE_MEM_OPENROUTER_API_KEY": "YOUR_OPENROUTER_API_KEY"
-}
-EOF
-```
-
-Replace `YOUR_OPENROUTER_API_KEY` with your actual API key.
-
-Then install hooks and start the worker:
-
-```bash
-bun run cursor:install
-bun run worker:start
-```
-
-## Step 4: Restart Cursor
-
-Close and reopen Cursor IDE for the hooks to take effect.
-
-## Step 5: Verify Installation
-
-```bash
-# Check worker is running
-bun run worker:status
-
-# Check hooks are installed
-bun run cursor:status
-```
-
-Open http://localhost:37777 to see the memory viewer.
-
-## Recommended Models
-
-### Free Models
-
-| Model | Provider | Notes |
-|-------|----------|-------|
-| `google/gemini-2.0-flash-exp:free` | Google | Fast, capable |
-| `xiaomi/mimo-v2-flash:free` | Xiaomi | Good general purpose |
-
-### Paid Models (Low Cost)
-
-| Model | Approx. Cost | Notes |
-|-------|--------------|-------|
-| `anthropic/claude-3-haiku` | ~$0.25/1M tokens | Fast, efficient |
-| `google/gemini-flash-1.5` | ~$0.075/1M tokens | Great value |
-| `mistralai/mistral-7b-instruct` | ~$0.07/1M tokens | Budget option |
-
-To specify a model, add to your settings:
-
-```json
-{
-  "CLAUDE_MEM_PROVIDER": "openrouter",
-  "CLAUDE_MEM_OPENROUTER_API_KEY": "your-key",
-  "CLAUDE_MEM_OPENROUTER_MODEL": "google/gemini-2.0-flash-exp:free"
-}
-```
-
-## Cost Management
-
-OpenRouter charges per token. To manage costs:
-
-1. **Use free models:** Several high-quality free models are available
-2. **Monitor usage:** Check your [OpenRouter dashboard](https://openrouter.ai/activity)
-3. **Set spending limits:** Configure limits in OpenRouter settings
-
-<Warning>
-**Cost awareness:** Unlike Gemini's free tier, OpenRouter paid models charge per request. Monitor your usage if using paid models.
-</Warning>
-
-## Troubleshooting
-
-### "OpenRouter API key not configured"
-
-Ensure your settings file exists with the correct format:
-
-```bash
-cat ~/.claude-mem/settings.json
-```
-
-Should output something like:
-```json
-{
-  "CLAUDE_MEM_PROVIDER": "openrouter",
-  "CLAUDE_MEM_OPENROUTER_API_KEY": "sk-or-..."
-}
-```
-
-### Model not found
-
-1. Check the model ID is correct at [OpenRouter Models](https://openrouter.ai/models)
-2. Some models may require payment - check if you have credits
-3. Free models have `:free` suffix in their ID
-
-### Rate limits
-
-OpenRouter rate limits vary by model and your account tier. If you hit limits:
-1. Wait briefly and retry
-2. Consider upgrading your OpenRouter account tier
-3. Switch to a less popular model
-
-### API errors
-
-Check the worker logs for details:
-
-```bash
-bun run worker:logs
-```
-
-Common issues:
- Invalid API key (regenerate at OpenRouter)
- Insufficient credits for paid models
- Model temporarily unavailable
-
-## Switching Providers Later
-
-You can switch between OpenRouter, Gemini, and Claude SDK at any time by updating your settings. No restart required - changes take effect on the next observation.
-
-```json
-{
-  "CLAUDE_MEM_PROVIDER": "gemini"
-}
-```
-
-## Next Steps
-
- [Cursor Integration Overview](/cursor/index) - All Cursor features
- [Gemini Setup](/cursor/gemini-setup) - Alternative free provider
- [Configuration Reference](../configuration) - All settings options
@@ -165,7 +165,7 @@ npm run build
 1. Make changes to React components in `src/ui/viewer/`
 2. Build: `npm run build`
 3. Sync to installed plugin: `npm run sync-marketplace`
-4. Restart worker: `npm run worker:restart`
+4. Restart worker: `claude-mem restart`
 5. Refresh browser at http://localhost:37777

 **Hot Reload**: Not currently supported. Full rebuild + restart required for changes.
@@ -395,7 +395,7 @@ When developing new features:
   ```bash
   npm run build
   npm run sync-marketplace
-   npm run worker:restart
+   claude-mem restart
   ```

 2. **Test in real session**:
@@ -560,7 +560,7 @@ export async function createObservation(

 ```bash
 export DEBUG=claude-mem:*
-npm run worker:restart
+claude-mem restart
 npm run worker:logs
 ```

@@ -36,41 +36,22 @@
          "introduction",
          "installation",
          "usage/getting-started",
-          "usage/openrouter-provider",
          "usage/gemini-provider",
          "usage/search-tools",
          "usage/claude-desktop",
          "usage/private-tags",
          "usage/export-import",
          "usage/manual-recovery",
-          "usage/folder-context",
          "beta-features",
          "endless-mode"
        ]
      },
-      {
-        "group": "Cursor Integration",
-        "icon": "wand-magic-sparkles",
-        "pages": [
-          "cursor/index",
-          "cursor/gemini-setup",
-          "cursor/openrouter-setup"
-        ]
-      },
-      {
-        "group": "Gemini CLI Integration",
-        "icon": "terminal",
-        "pages": [
-          "gemini-cli/setup"
-        ]
-      },
      {
        "group": "Best Practices",
        "icon": "lightbulb",
        "pages": [
          "context-engineering",
-          "progressive-disclosure",
-          "smart-explore-benchmark"
+          "progressive-disclosure"
        ]
      },
      {
@@ -81,8 +62,7 @@
          "modes",
          "development",
          "troubleshooting",
-          "platform-integration",
-          "openclaw-integration"
+          "platform-integration"
        ]
      },
      {
@@ -94,7 +94,7 @@ git checkout beta/endless-mode
 npm install

 # Restart the worker
-npm run worker:restart
+claude-mem restart
 ```

 **To return to stable:**
@@ -103,7 +103,7 @@ npm run worker:restart
 cd ~/.claude/plugins/marketplaces/thedotmack/
 git checkout main
 npm install
-npm run worker:restart
+claude-mem restart
 ```

 ## Summary
--- a/Show More
+++ b/Show More