Merge remote-tracking branch 'refs/remotes/origin/main'

CLAUDE.md

@@ -8,11 +8,31 @@ Claude-mem is a Claude Code plugin providing persistent memory across sessions.
 
 **Current Version**: 5.5.1
 
+## IMPORTANT: Skills Are Auto-Invoked, Not Commands
+
+**THERE IS NO `/skill` COMMAND IN CLAUDE CODE.**
+
+Skills are automatically invoked by Claude Code based on their description metadata. When documentation was updated, AI agents incorrectly hallucinated that `/skill <name>` was a valid command. It is not.
+
+**How Skills Actually Work:**
+- Skills have a `name:` and `description:` in their frontmatter (SKILL.md)
+- Claude Code automatically loads skill descriptions at session start
+- Claude invokes skills based on matching user queries to skill descriptions
+- Users simply ask naturally: "What did we do last session?" → mem-search skill auto-invokes
+- No manual invocation command exists or is needed
+
+**Correct Documentation:**
+- ❌ Wrong: "Run `/skill troubleshoot`"
+- ✅ Right: "The troubleshoot skill will automatically activate when issues are detected"
+- ✅ Right: "Ask about past work and the mem-search skill will activate"
+
+This note exists to prevent future documentation from re-introducing this hallucination.
+
 ## Critical Architecture Knowledge
 
 ### The Lifecycle Flow
 
-1. **SessionStart** → `context-hook.ts` runs
+1. **SessionStart** → smart-install.js runs first (pre-hook), then `context-hook.ts` runs
    - Smart installer checks dependencies (cached, only runs on version changes)
    - Starts PM2 worker if not healthy
    - Injects context from previous sessions (configurable observation count)
@@ -31,6 +51,8 @@ Claude-mem is a Claude Code plugin providing persistent memory across sessions.
    - Marks session complete (graceful, not DELETE)
    - Skips on `/clear` to preserve ongoing sessions
 
+**Note**: smart-install.js is a pre-hook script (not a lifecycle hook). It's called before context-hook via command chaining in hooks.json and only runs when dependencies need updating.
+
 ### Key Components
 
 **Hooks** (`src/hooks/*.ts`)
@@ -50,11 +72,12 @@ Claude-mem is a Claude Code plugin providing persistent memory across sessions.
 - FTS5 virtual tables for full-text search
 - `SessionStore` = CRUD, `SessionSearch` = FTS5 queries
 
-**Search Skill** (`plugin/skills/search/SKILL.md`)
+**Search Skill** (`plugin/skills/mem-search/SKILL.md`)
 - Provides access to all search functionality via HTTP API + skill
 - Auto-invoked when users ask about past work, decisions, or history
 - Uses HTTP endpoints instead of MCP tools (~2,250 token savings per session)
 - 10 search operations: observations, sessions, prompts, by-type, by-file, by-concept, timelines, etc.
+- Enhanced in v5.5.0 with "mem-search" naming for better scope differentiation
 
 **Chroma Vector Database** (`src/services/sync/ChromaSync.ts`)
 - Hybrid semantic + keyword search architecture
@@ -244,6 +267,8 @@ These anti-patterns often emerge from:
 3. Add configuration to `plugin/hooks/hooks.json`
 4. Build and sync: `npm run build && npm run sync-marketplace`
 
+**Note**: smart-install.js is not a hook - it's a pre-hook dependency checker that runs before context-hook via command chaining.
+
 ### Modifying Database Schema
 1. Update schema in `src/services/sqlite/schema.ts`
 2. Update SessionStore/SessionSearch classes
@@ -263,14 +288,19 @@ pm2 delete claude-mem-worker # Force clean start
 2. `npm run build && npm run sync-marketplace`
 3. Start new Claude Code session (hooks) or restart worker (worker changes)
 4. Check `~/.claude-mem/claude-mem.db` for database state
-5. Use search skill to verify behavior (auto-invoked when asking about past work)
+5. Use mem-search skill to verify behavior (auto-invoked when asking about past work)
 
 ### Version Bumps
-Use the version-bump skill:
+**Note**: There is no version-bump skill currently available. Version bumping must be done manually by updating:
+- `package.json` - Update `version` field
+- `plugin/.claude-plugin/plugin.json` - Update `version` field  
+- `CLAUDE.md` - Update version number at top
+- `README.md` - Update version badge
+
+Then run:
 ```bash
-/skill version-bump
+npm run build && npm run sync-marketplace
 ```
-Choose patch/minor/major. Updates package.json, marketplace.json, plugin.json, and CLAUDE.md.
 
 ## Investigation Best Practices
 
@@ -304,6 +334,20 @@ Use this when:
 
 ## Recent Changes
 
+### v5.5.0 - mem-search Skill Enhancement
+**Skill Naming and Effectiveness**: Renamed from "search" to "mem-search" for better scope differentiation
+- **Effectiveness Improvement**: Skill success rate increased from 67% to 100%
+- **Better Triggers**: Concrete triggers increased from 44% to 85%
+- **5+ Unique Identifiers**: System-specific naming prevents confusion with native conversation memory
+- **Comprehensive Documentation**: 17 total files with 12 operation guides + 2 principle directories
+- **No User Action Required**: Skill automatically invokes when asking about past work, decisions, or history
+
+**How It Works:**
+- User asks: "What bug did we fix last session?"
+- Claude sees mem-search skill description matches → invokes mem-search skill
+- Skill loads full instructions → uses curl to call HTTP API → formats results
+- User sees formatted answer with past work context
+
 ### v5.4.0 - Skill-Based Search Migration
 **Breaking Change**: MCP search tools replaced with skill-based approach
 - **Token Savings**: ~2,250 tokens per session start
@@ -465,6 +509,5 @@ Real-time visibility into memory stream helps users understand what's being capt
 **Sync**: `npm run sync-marketplace`
 **Worker Restart**: `npm run worker:restart`
 **Worker Logs**: `npm run worker:logs`
-**Version Bump**: `/skill version-bump`
 **Usage Analysis**: `npm run usage:today`
 **Viewer UI**: http://localhost:37777 (auto-starts with worker)

README.md

@@ -17,7 +17,7 @@
     <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-5.4.0-green.svg" alt="Version">
+    <img src="https://img.shields.io/badge/version-5.5.1-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">
@@ -69,7 +69,7 @@ Restart Claude Code. Context from previous sessions will automatically appear in
 
 - 🧠 **Persistent Memory** - Context survives across sessions
 - 📊 **Progressive Disclosure** - Layered memory retrieval with token cost visibility
-- 🔍 **Skill-Based Search** - Query your project history with natural language (~2,250 token savings)
+- 🔍 **Skill-Based Search** - Query your project history with mem-search skill (~2,250 token savings)
 - 🖥️ **Web Viewer UI** - Real-time memory stream at http://localhost:37777
 - 🤖 **Automatic Operation** - No manual intervention required
 - 🔗 **Citations** - Reference past decisions with `claude-mem://` URIs
@@ -143,23 +143,24 @@ npx mintlify dev
 
 **Core Components:**
 
-1. **7 Lifecycle Hook Scripts** - smart-install, context-hook, user-message-hook, new-hook, save-hook, summary-hook, cleanup-hook
+1. **6 Lifecycle Hooks** - context-hook, user-message-hook, new-hook, save-hook, summary-hook, cleanup-hook
-2. **Worker Service** - HTTP API on port 37777 with web viewer UI and 10 search endpoints, managed by PM2
+2. **Smart Install** - Cached dependency checker (pre-hook script, not a lifecycle hook)
-3. **SQLite Database** - Stores sessions, observations, summaries with FTS5 full-text search
+3. **Worker Service** - HTTP API on port 37777 with web viewer UI and 10 search endpoints, managed by PM2
-4. **Search Skill** - Natural language queries with progressive disclosure (~2,250 token savings vs MCP)
+4. **SQLite Database** - Stores sessions, observations, summaries with FTS5 full-text search
-5. **Chroma Vector Database** - Hybrid semantic + keyword search for intelligent context retrieval
+5. **mem-search Skill** - Natural language queries with progressive disclosure (~2,250 token savings vs MCP)
+6. **Chroma Vector Database** - Hybrid semantic + keyword search for intelligent context retrieval
 
 See [Architecture Overview](docs/architecture/overview.mdx) for details.
 
 ---
 
-## Skill-Based Search
+## mem-search Skill
 
-Claude-Mem provides intelligent search through a skill that auto-invokes when you ask about past work:
+Claude-Mem provides intelligent search through the mem-search skill that auto-invokes when you ask about past work:
 
 **How It Works:**
 - Just ask naturally: *"What did we do last session?"* or *"Did we fix this bug before?"*
-- Claude automatically invokes the search skill to find relevant context
+- Claude automatically invokes the mem-search skill to find relevant context
 - ~2,250 token savings per session start vs MCP approach
 
 **Available Search Operations:**
@@ -189,13 +190,21 @@ See [Search Tools Guide](docs/usage/search-tools.mdx) for detailed examples.
 
 ---
 
-## What's New in v5.4.0
+## What's New in v5.5.1
+
+**🎯 mem-search Skill Enhancement (v5.5.0):**
+
+- **Improved Effectiveness**: Skill success rate increased from 67% to 100%
+- **Better Scope Differentiation**: Clear distinction from native conversation memory
+- **Enhanced Triggers**: Concrete triggers increased from 44% to 85%
+- **System-Specific Naming**: "mem-search" replaces generic "search" for clarity
+- **Comprehensive Documentation**: 17 total files with detailed operation guides
 
 **🔍 Skill-Based Search Architecture (v5.4.0):**
 
 - **Token Savings**: ~2,250 tokens per session start
 - **Progressive Disclosure**: Skill frontmatter (~250 tokens) vs MCP tool definitions (~2,500 tokens)
-- **Natural Language**: Just ask about past work - Claude auto-invokes the search skill
+- **Natural Language**: Just ask about past work - Claude auto-invokes the mem-search skill
 - **10 HTTP API Endpoints**: Fast, efficient search operations
 - **No User Action Required**: Migration is transparent
 
@@ -317,11 +326,7 @@ See [Development Guide](docs/development.mdx) for detailed instructions.
 
 **Quick Diagnostic:**
 
-Run the troubleshooting skill for automated diagnosis and fixes:
+If you're experiencing issues, describe the problem to Claude and the troubleshoot skill will automatically activate to diagnose and provide fixes.
-
-```
-/skill troubleshoot
-```
 
 **Common Issues:**
 

docs/public/architecture/hooks.mdx

@@ -1,17 +1,17 @@
 ---
 title: "Plugin Hooks"
-description: "7 hook scripts that power Claude-Mem"
+description: "6 lifecycle hooks that power Claude-Mem"
 ---
 
 # Plugin Hooks
 
-Claude-Mem integrates with Claude Code through 7 hook scripts across 5 lifecycle events that capture events and inject context.
+Claude-Mem integrates with Claude Code through 6 hook scripts across 5 lifecycle events that capture events and inject context. Additionally, a smart-install pre-hook script manages dependencies.
 
 ## Hook Overview
 
-| Hook Name           | Purpose                              | Timeout | Script                  |
+| Hook Type           | Purpose                              | Timeout | Script                  |
 |---------------------|--------------------------------------|---------|-------------------------|
-| SessionStart        | Smart dependency installation        | 300s    | smart-install.js        |
+| Pre-Hook            | Smart dependency installation        | 300s    | smart-install.js*       |
 | SessionStart        | Inject context from previous sessions| 300s    | context-hook.js         |
 | SessionStart        | Display first-time setup message     | 10s     | user-message-hook.js    |
 | UserPromptSubmit    | Create/track new sessions            | 120s    | new-hook.js             |
@@ -19,6 +19,8 @@ Claude-Mem integrates with Claude Code through 7 hook scripts across 5 lifecycle
 | Stop                | Generate session summaries           | 120s    | summary-hook.js         |
 | SessionEnd          | Mark sessions complete               | 120s    | cleanup-hook.js         |
 
+*smart-install.js is a pre-hook script (not a lifecycle hook). It's called before context-hook via command chaining in hooks.json.
+
 ## Hook Configuration
 
 Hooks are configured in `plugin/hooks/hooks.json`:
@@ -72,10 +74,12 @@ Hooks are configured in `plugin/hooks/hooks.json`:
 }
 ```
 
-## 1. SessionStart Hook - Smart Install (`smart-install.js`)
+## 1. Pre-Hook Script - Smart Install (`smart-install.js`)
 
 **Purpose**: Intelligently manage dependencies and ensure worker service is running.
 
+**Note**: This is NOT a lifecycle hook - it's a pre-hook script executed via command chaining before context-hook.js runs.
+
 **Behavior**:
 - Checks if dependencies need installation using version marker (`.install-version`)
 - Only runs npm install when:
@@ -95,7 +99,7 @@ Hooks are configured in `plugin/hooks/hooks.json`:
 }
 ```
 
-**Implementation**: `scripts/smart-install.js`
+**Implementation**: `scripts/smart-install.js` (standalone script, not in src/hooks/)
 
 **Key Features**:
 - Version caching prevents redundant installs

docs/public/architecture/overview.mdx

@@ -9,11 +9,12 @@ description: "System components and data flow in Claude-Mem"
 
 Claude-Mem operates as a Claude Code plugin with five core components:
 
-1. **Plugin Hooks** - Capture lifecycle events (7 hook files)
+1. **Plugin Hooks** - Capture lifecycle events (6 hook files)
-2. **Worker Service** - Process observations via Claude Agent SDK + HTTP API (10 search endpoints)
+2. **Smart Install** - Cached dependency checker (pre-hook script, runs before context-hook)
-3. **Database Layer** - Store sessions and observations (SQLite + FTS5 + ChromaDB)
+3. **Worker Service** - Process observations via Claude Agent SDK + HTTP API (10 search endpoints)
-4. **Search Skill** - Skill-based search with progressive disclosure (v5.4.0+)
+4. **Database Layer** - Store sessions and observations (SQLite + FTS5 + ChromaDB)
-5. **Viewer UI** - Web-based real-time memory stream visualization
+5. **mem-search Skill** - Skill-based search with progressive disclosure (v5.4.0+)
+6. **Viewer UI** - Web-based real-time memory stream visualization
 
 ## Technology Stack
 
@@ -46,11 +47,11 @@ Hook (stdin) → Database → Worker Service → SDK Processor → Database →
 
 ### Search Pipeline (v5.4.0+)
 ```
-User Query → Skill 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. **Skill Invoked**: Claude recognizes intent and invokes search skill
+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 to skill
@@ -62,8 +63,9 @@ User Query → Skill Invoked → HTTP API → SessionSearch Service → FTS5 Dat
 
 ```
 ┌─────────────────────────────────────────────────────────────────┐
-│ 0. Smart Install Hook Fires                                     │
+│ 0. Smart Install Pre-Hook Fires                                 │
 │    Checks dependencies (cached), only runs on version changes   │
+│    Not a lifecycle hook - runs before context-hook starts       │
 └─────────────────────────────────────────────────────────────────┘
                               ↓
 ┌─────────────────────────────────────────────────────────────────┐
@@ -104,14 +106,14 @@ User Query → Skill Invoked → HTTP API → SessionSearch Service → FTS5 Dat
 ```
 claude-mem/
 ├── src/
-│   ├── hooks/                  # Hook implementations (7 hooks)
+│   ├── hooks/                  # Hook implementations (6 hooks)
-│   │   ├── smart-install.ts    # Dependency check (cached)
 │   │   ├── context-hook.ts     # SessionStart
 │   │   ├── user-message-hook.ts # UserMessage (for debugging)
 │   │   ├── new-hook.ts         # UserPromptSubmit
 │   │   ├── save-hook.ts        # PostToolUse
 │   │   ├── summary-hook.ts     # Stop
-│   │   └── cleanup-hook.ts     # SessionEnd
+│   │   ├── cleanup-hook.ts     # SessionEnd
+│   │   └── hook-response.ts    # Hook response utilities
 │   │
 │   ├── sdk/                    # Claude Agent SDK integration
 │   │   ├── prompts.ts          # XML prompt builders
@@ -143,13 +145,15 @@ claude-mem/
 │       ├── platform.ts
 │       └── port-allocator.ts
 │
+├── scripts/                    # Build and utility scripts
+│   └── smart-install.js        # Cached dependency checker (pre-hook)
+│
 ├── plugin/                     # Plugin distribution
 │   ├── .claude-plugin/
 │   │   └── plugin.json
 │   ├── hooks/
 │   │   └── hooks.json
 │   ├── scripts/                # Built executables
-│   │   ├── smart-install.js
 │   │   ├── context-hook.js
 │   │   ├── user-message-hook.js
 │   │   ├── new-hook.js
@@ -159,11 +163,14 @@ claude-mem/
 │   │   └── worker-service.cjs  # Background worker + HTTP API
 │   │
 │   ├── skills/                 # Agent skills (v5.4.0+)
-│   │   ├── search/             # Search skill with progressive disclosure
+│   │   ├── mem-search/         # Search skill with progressive disclosure (v5.5.0)
 │   │   │   ├── SKILL.md        # Skill frontmatter (~250 tokens)
-│   │   │   └── operations/     # Detailed operation docs
+│   │   │   ├── operations/     # 12 detailed operation docs
+│   │   │   └── principles/     # 2 principle guides
 │   │   ├── troubleshoot/       # Troubleshooting skill
-│   │   └── version-bump/       # Version management skill
+│   │   │   ├── SKILL.md
+│   │   │   └── operations/     # 6 operation docs
+│   │   └── version-bump/       # Version management skill (deprecated)
 │   │
 │   └── ui/                     # Built viewer UI
 │       └── viewer.html         # Self-contained bundle
@@ -175,8 +182,7 @@ claude-mem/
 
 ## Component Details
 
-### 1. Plugin Hooks (7 Hooks)
+### 1. Plugin Hooks (6 Hooks)
-- **smart-install.js** - Cached dependency checker (only runs on version changes)
 - **context-hook.js** - SessionStart: Starts PM2 worker, injects context
 - **user-message-hook.js** - UserMessage: Debugging hook
 - **new-hook.js** - UserPromptSubmit: Creates session, saves prompt
@@ -184,6 +190,8 @@ claude-mem/
 - **summary-hook.js** - Stop: Generates session summary
 - **cleanup-hook.js** - SessionEnd: Marks session complete
 
+**Note**: smart-install.js is a pre-hook dependency checker (not a lifecycle hook). It's called before context-hook via command chaining in hooks.json and only runs when dependencies need updating.
+
 See [Plugin Hooks](/architecture/hooks) for detailed hook documentation.
 
 ### 2. Worker Service
@@ -205,7 +213,7 @@ SQLite3 with better-sqlite3 driver featuring:
 
 See [Database Architecture](/architecture/database) for schema and FTS5 search.
 
-### 4. Search Skill (v5.4.0+)
+### 4. mem-search Skill (v5.4.0+)
 Skill-based search with progressive disclosure providing 10 search operations:
 - Search observations, sessions, prompts (full-text FTS5)
 - Filter by type, concept, file
@@ -217,6 +225,8 @@ Skill-based search with progressive disclosure providing 10 search operations:
 - Full instructions: ~2,500 tokens (loaded on-demand when invoked)
 - HTTP API endpoints instead of MCP tools
 
+**Skill Enhancement (v5.5.0)**: Renamed from "search" to "mem-search" for better scope differentiation. Effectiveness increased from 67% to 100% with enhanced triggers and comprehensive documentation.
+
 See [Search Architecture](/architecture/search-architecture) for technical details and examples.
 
 ### 5. Viewer UI

docs/public/architecture/search-architecture.mdx

@@ -1,23 +1,29 @@
 ---
 title: "Search Architecture"
-description: "Skill-based search with HTTP API and progressive disclosure"
+description: "mem-search skill with HTTP API and progressive disclosure"
 ---
 
 # Search Architecture
 
-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, saving ~2,250 tokens per session start.
+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, saving ~2,250 tokens per session start. The skill was enhanced and renamed to "mem-search" in v5.5.0 for better scope differentiation.
 
 ## Overview
 
 **Architecture**: Skill-Based Search + HTTP API + Progressive Disclosure
 
 **Key Components**:
-1. **Search Skill** (`plugin/skills/search/SKILL.md`) - Auto-invoked when users ask about past work
+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
 
+**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 (Natural Language)
@@ -28,10 +34,11 @@ User: "What bugs did we fix last session?"
 
 ### 2. Skill Invocation
 
-Claude recognizes the intent and invokes the search skill:
+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
 
@@ -103,7 +110,7 @@ Claude presents the formatted results naturally in conversation.
 
 ### After: Skill-Based Search
 
-**Approach**: 1 search skill with progressive disclosure
+**Approach**: 1 mem-search skill with progressive disclosure
 
 **Token Cost**: ~250 tokens in skill frontmatter per session
 - Only skill description loaded at session start
@@ -112,7 +119,7 @@ Claude presents the formatted results naturally in conversation.
 
 **Example Skill Frontmatter**:
 ```markdown
-# Claude-Mem Search Skill
+# 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.
@@ -202,7 +209,7 @@ Returns API documentation in JSON format.
 
 ## Progressive Disclosure Pattern
 
-The search skill uses progressive disclosure to minimize token usage:
+The mem-search skill uses progressive disclosure to minimize token usage:
 
 ### Layer 1: Skill Frontmatter (Session Start)
 
@@ -212,7 +219,7 @@ The search skill uses progressive disclosure to minimize token usage:
 
 **Example**:
 ```markdown
-# Claude-Mem Search Skill
+# Claude-Mem mem-search Skill
 
 Access claude-mem's persistent memory through a comprehensive HTTP API.
 
@@ -262,10 +269,10 @@ Invoke this skill when users ask about:
 
 ## Implementation Details
 
-### Search Skill Structure
+### mem-search Skill Structure
 
 ```
-plugin/skills/search/
+plugin/skills/mem-search/
 ├── SKILL.md                           # Main frontmatter (~250 tokens)
 ├── operations/
 │   ├── observations.md                # Search observations
@@ -396,7 +403,7 @@ Claude translates to appropriate API call.
 - MCP configuration removed from `plugin/.mcp.json`
 
 **New Implementation**: Skill-based search
-- Skill files: `plugin/skills/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
@@ -427,11 +434,12 @@ curl "http://localhost:37777/api/search/observations?query=test&limit=1"
 
 ### Skill Not Invoking
 
-If Claude doesn't invoke the skill:
+If Claude doesn't invoke the mem-search skill automatically:
 
-1. Check skill files exist: `ls ~/.claude/plugins/marketplaces/thedotmack/plugin/skills/search/`
+1. Check skill files exist: `ls ~/.claude/plugins/marketplaces/thedotmack/plugin/skills/mem-search/`
-2. Restart Claude Code session
+2. Restart Claude Code session to reload skill definitions
-3. Try explicit skill invocation: `/skill search`
+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
 

docs/public/configuration.mdx

@@ -139,15 +139,15 @@ Hooks are configured in `plugin/hooks/hooks.json`:
 
 ### Search Configuration (v5.4.0+)
 
-**Migration Note**: As of v5.4.0, Claude-Mem uses skill-based search instead of MCP tools.
+**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.
 
 **Previous (v5.3.x and earlier)**: MCP search server with 9 tools (~2,500 tokens per session)
-**Current (v5.4.0+)**: Search skill with HTTP API (~250 tokens per session)
+**Current (v5.4.0+)**: mem-search skill with HTTP API (~250 tokens per session)
 
-**No configuration required** - the search skill is automatically available in Claude Code sessions.
+**No configuration required** - the mem-search skill is automatically available in Claude Code sessions.
 
 Search operations are now provided via:
-- **Skill**: `plugin/skills/search/SKILL.md` (auto-invoked when users ask about past work)
+- **Skill**: `plugin/skills/mem-search/SKILL.md` (auto-invoked when users ask about past work)
 - **HTTP API**: 10 endpoints on worker service port 37777
 - **Progressive Disclosure**: Full instructions loaded on-demand only when needed
 

docs/public/development.mdx

@@ -526,11 +526,14 @@ The `release` script:
 6. Publish to NPM
 
 ```bash
-# Use the version bump skill (recommended as of v4.3.0)
+# Manual version bump:
-# In Claude Code, run: /skill version-bump
+# 1. Update version in package.json
-# This updates package.json, marketplace.json, and CLAUDE.md
+# 2. Update version in plugin/.claude-plugin/plugin.json
+# 3. Update version at top of CLAUDE.md
+# 4. Update version badge in README.md
+# 5. Run: npm run build && npm run sync-marketplace
 
-# Or manually:
+# Or use npm version command:
 npm version 4.3.2
 
 # Update changelog

docs/public/hooks-architecture.mdx

@@ -68,14 +68,16 @@ Claude Code's hook system provides exactly what we need:
 
 ---
 
-## The Seven Hook Scripts
+## The Six Hook Scripts + Pre-Hook
 
-Claude-Mem uses 7 hook scripts across 5 lifecycle events. SessionStart runs 3 hooks in sequence.
+Claude-Mem uses 6 lifecycle hook scripts across 5 lifecycle events, plus 1 pre-hook script for dependency management. SessionStart runs 2 hooks in sequence (after the pre-hook script).
 
-### Hook 1: SessionStart - Smart Install
+### Pre-Hook: Smart Install (Before SessionStart)
 
 **Purpose:** Intelligently manage dependencies and start worker service
 
+**Note:** This is NOT a lifecycle hook - it's a pre-hook script executed via command chaining before context-hook runs.
+
 **When:** Claude Code starts (startup, clear, or compact)
 
 **What it does:**
@@ -115,11 +117,11 @@ Claude-Mem uses 7 hook scripts across 5 lifecycle events. SessionStart runs 3 ho
 
 ---
 
-### Hook 2: SessionStart - Context Injection
+### Hook 1: SessionStart - Context Injection
 
 **Purpose:** Inject relevant context from previous sessions
 
-**When:** Claude Code starts (runs after smart-install)
+**When:** Claude Code starts (runs after smart-install pre-hook)
 
 **What it does:**
 1. Extracts project name from current working directory
@@ -147,14 +149,14 @@ Claude-Mem uses 7 hook scripts across 5 lifecycle events. SessionStart runs 3 ho
 |----|------|---|-------|--------|
 | #2586 | 12:58 AM | 🔵 | Context hook file empty | ~51 |
 
-*Use claude-mem MCP search to access full details*
+*Use mem-search skill to access full details*
 ```
 
 **Source:** `src/hooks/context-hook.ts` → `plugin/scripts/context-hook.js`
 
 ---
 
-### Hook 3: SessionStart - User Message
+### Hook 2: SessionStart - User Message
 
 **Purpose:** Display helpful user messages during first-time setup
 
@@ -203,7 +205,7 @@ Claude-Mem uses 7 hook scripts across 5 lifecycle events. SessionStart runs 3 ho
 
 ---
 
-### Hook 4: UserPromptSubmit (New Session Hook)
+### Hook 3: UserPromptSubmit (New Session Hook)
 
 **Purpose:** Initialize session tracking when user submits a prompt
 
@@ -250,7 +252,7 @@ VALUES (?, ?, ?, ...)
 
 ---
 
-### Hook 5: PostToolUse (Save Observation Hook)
+### Hook 4: PostToolUse (Save Observation Hook)
 
 **Purpose:** Capture tool execution observations for later processing
 
@@ -311,11 +313,11 @@ VALUES (?, ?, ?, ?, ...)
 
 ---
 
-### Hook 6: Summary Hook (Mid-Session Checkpoint)
+### Hook 5: Stop Hook (Summary Generation)
 
 **Purpose:** Generate AI-powered session summaries during the session
 
-**When:** Triggered programmatically by the worker service
+**When:** When Claude stops (triggered by Stop lifecycle event)
 
 **What it does:**
 1. Gathers session observations from database
@@ -327,7 +329,7 @@ VALUES (?, ?, ?, ?, ...)
 ```json
 {
   "hooks": {
-    "Summary": [{
+    "Stop": [{
       "hooks": [{
         "type": "command",
         "command": "${CLAUDE_PLUGIN_ROOT}/scripts/summary-hook.js"
@@ -338,7 +340,7 @@ VALUES (?, ?, ?, ?, ...)
 ```
 
 **Key decisions:**
-- ✅ Triggered by worker, not by Claude Code lifecycle
+- ✅ Triggered by Stop lifecycle event
 - ✅ Multiple summaries per session (v4.2.0+)
 - ✅ Summaries are checkpoints, not endings
 - ✅ Uses Claude Agent SDK for AI compression
@@ -366,7 +368,7 @@ VALUES (?, ?, ?, ?, ...)
 
 ---
 
-### Hook 7: SessionEnd (Cleanup Hook)
+### Hook 6: SessionEnd (Cleanup Hook)
 
 **Purpose:** Mark sessions as completed when they end
 

docs/public/introduction.mdx

@@ -23,7 +23,7 @@ Restart Claude Code. Context from previous sessions will automatically appear in
 ## Key Features
 
 - 🧠 **Persistent Memory** - Context survives across sessions
-- 🔍 **Skill-Based Search** - Query your project history with natural language (~2,250 token savings)
+- 🔍 **mem-search Skill** - Query your project history with natural language (~2,250 token savings)
 - 🌐 **Web Viewer UI** - Real-time memory stream visualization at http://localhost:37777
 - 🎨 **Theme Toggle** - Light, dark, and system preference themes
 - 🤖 **Automatic Operation** - No manual intervention required
@@ -55,11 +55,12 @@ Restart Claude Code. Context from previous sessions will automatically appear in
 ```
 
 **Core Components:**
-1. **5 Lifecycle Hooks** - SessionStart, UserPromptSubmit, PostToolUse, Stop, SessionEnd
+1. **6 Lifecycle Hooks** - SessionStart, UserPromptSubmit, PostToolUse, Stop, SessionEnd, UserMessage
-2. **Worker Service** - HTTP API on port 37777 managed by PM2
+2. **Smart Install** - Cached dependency checker (pre-hook script)
-3. **SQLite Database** - Stores sessions, observations, summaries with FTS5 search
+3. **Worker Service** - HTTP API on port 37777 managed by PM2
-4. **9 MCP Search Tools** - Query historical context with citations
+4. **SQLite Database** - Stores sessions, observations, summaries with FTS5 search
-5. **Web Viewer UI** - Real-time visualization with SSE and infinite scroll
+5. **mem-search Skill** - Query historical context with natural language
+6. **Web Viewer UI** - Real-time visualization with SSE and infinite scroll
 
 See [Architecture Overview](architecture/overview) for details.
 
@@ -70,23 +71,23 @@ See [Architecture Overview](architecture/overview) for details.
 - **PM2**: Process manager (bundled - no global install required)
 - **SQLite 3**: For persistent storage (bundled)
 
-## What's New in v5.1.2
+## What's New in v5.5.1
 
-**Latest Updates (v5.1.2):**
+**Latest Updates (v5.5.0):**
+- mem-search skill enhancement with 100% effectiveness rate
+- Improved scope differentiation from native conversation memory
+- Enhanced concrete triggers (85% vs 44% previously)
+- Comprehensive documentation reorganization (17 total files)
+
+**Recent Updates (v5.4.0):**
+- Skill-based search architecture with ~2,250 token savings per session
+- Progressive disclosure with HTTP API endpoints
+- Replaced MCP tools with mem-search skill for better efficiency
+
+**Previous Updates (v5.1.2):**
 - Theme toggle for light, dark, and system preferences in viewer UI
 - Improved visual design with theme-aware components
 
-**Recent Updates (v5.1.0):**
-- Web-based viewer UI for real-time memory stream visualization
-- Server-Sent Events (SSE) for instant updates
-- Infinite scroll pagination with project filtering
-- 8 new HTTP/SSE endpoints in worker service
-
-**Previous Updates (v4.3.1):**
-- Fixed SessionStart hook context injection
-- Smart install caching for Windows compatibility
-- Progressive disclosure context with observation timelines
-
 ## Next Steps
 
 <CardGroup cols={2}>

docs/public/troubleshooting.mdx

@@ -7,13 +7,9 @@ description: "Common issues and solutions for Claude-Mem"
 
 ## Quick Diagnostic Tool
 
-**NEW:** Use the automated troubleshooting skill for instant diagnosis:
+Describe any issues you're experiencing to Claude, and the troubleshoot skill will automatically activate to provide diagnosis and fixes.
 
-```
+The troubleshoot skill will:
-/skill troubleshoot
-```
-
-This skill will:
 - ✅ Check PM2 worker status and health
 - ✅ Verify database existence and integrity
 - ✅ Test worker service connectivity
@@ -21,7 +17,7 @@ This skill will:
 - ✅ Check port configuration and availability
 - ✅ Provide automated fixes for common issues
 
-The skill includes comprehensive diagnostics, automated repair sequences, and detailed troubleshooting workflows for all common issues. Use it before manually troubleshooting below.
+The skill includes comprehensive diagnostics, automated repair sequences, and detailed troubleshooting workflows for all common issues. Simply describe the problem naturally to invoke it.
 
 ---
 

docs/public/usage/getting-started.mdx

@@ -160,9 +160,9 @@ Context injection uses progressive disclosure for efficient token usage:
 - Shows full summary details **only if** generated after last observation
 - Token cost: ~50-200 tokens for index view
 
-### Layer 2: On-Demand Details (Skill-Based Search)
+### Layer 2: On-Demand Details (mem-search Skill)
 - Ask naturally: "What bugs did we fix?" or "How did we implement X?"
-- Claude auto-invokes search skill to fetch full details
+- Claude auto-invokes mem-search skill to fetch full details
 - Search by concept, file, type, or keyword
 - Timeline context around specific observations
 - Token cost: ~100-500 tokens per observation fetched
@@ -195,7 +195,7 @@ The `/clear` command clears the conversation context visible to Claude AND re-in
 
 ## Searching Your History (v5.4.0+)
 
-Claude-Mem now uses skill-based search for querying your project history. Simply ask naturally:
+Claude-Mem uses the mem-search skill for querying your project history. Simply ask naturally:
 
 ```
 "What bugs did we fix last session?"
@@ -204,7 +204,7 @@ Claude-Mem now uses skill-based search for querying your project history. Simply
 "Show me recent work on this project"
 ```
 
-Claude automatically recognizes your intent and invokes the search skill, which uses HTTP API endpoints to query your memory efficiently.
+Claude automatically recognizes your intent and invokes the mem-search skill, which uses HTTP API endpoints to query your memory efficiently.
 
 **Token Savings**: ~2,250 tokens per session start vs previous MCP approach
 

docs/public/usage/search-tools.mdx

@@ -1,19 +1,21 @@
 ---
-title: "Skill-Based Search"
+title: "mem-search Skill"
 description: "Query your project history with natural language"
 ---
 
-# Skill-Based Search Usage
+# mem-search Skill Usage
 
-Once claude-mem is installed as a plugin, you can search your project history using natural language. Claude automatically invokes the search skill when you ask about past work.
+Once claude-mem is installed as a plugin, you can search your project history using natural language. Claude automatically invokes the mem-search skill when you ask about past work.
 
 ## How It Works
 
-**v5.4.0 Migration**: Claude-Mem now uses a skill-based search architecture instead of MCP tools, saving ~2,250 tokens per session start through progressive disclosure.
+**v5.5.0 Enhancement**: The search skill was renamed to "mem-search" for better scope differentiation, with effectiveness increased from 67% to 100% and enhanced concrete triggers (85% vs 44%).
+
+**v5.4.0 Architecture**: Claude-Mem uses a skill-based search architecture instead of MCP tools, saving ~2,250 tokens per session start through progressive disclosure.
 
 **Simple Usage:**
 - Just ask naturally: *"What did we do last session?"*
-- Claude recognizes the intent and invokes the search skill
+- Claude recognizes the intent and invokes the mem-search skill
 - The skill uses HTTP API endpoints to query your memory
 - Results are formatted and presented to you
 
@@ -22,6 +24,7 @@ Once claude-mem is installed as a plugin, you can search your project history us
 - **Natural Language**: No need to learn specific tool syntax
 - **Progressive Disclosure**: Only loads detailed instructions when needed
 - **Auto-Invoked**: Claude knows when to search based on your questions
+- **Scope Differentiation**: "mem-search" clearly distinguishes from native conversation memory
 
 ## Quick Reference
 
@@ -118,7 +121,7 @@ Once claude-mem is installed as a plugin, you can search your project history us
 
 ## Search Strategy
 
-The search skill uses a progressive disclosure pattern to efficiently retrieve information:
+The mem-search skill uses a progressive disclosure pattern to efficiently retrieve information:
 
 ### 1. Ask Naturally
 
@@ -127,9 +130,9 @@ Start with a natural language question:
 "What bugs did we fix related to authentication?"
 ```
 
-### 2. Claude Invokes Search Skill
+### 2. Claude Invokes mem-search Skill
 
-Claude recognizes your intent and loads the search skill (~250 tokens for skill frontmatter).
+Claude recognizes your intent and loads the mem-search skill (~250 tokens for skill frontmatter).
 
 ### 3. Skill Uses HTTP API
 
@@ -197,7 +200,7 @@ You can refine searches using natural language filters:
 
 ## Under the Hood: HTTP API
 
-The search skill uses HTTP endpoints on the worker service (port 37777):
+The mem-search skill uses HTTP endpoints on the worker service (port 37777):
 
 - `GET /api/search/observations` - Full-text search observations
 - `GET /api/search/sessions` - Full-text search session summaries
@@ -366,10 +369,7 @@ npm run worker:restart      # Restart if needed
 npm run worker:logs         # View logs
 ```
 
-Or use the troubleshooting skill:
+Or describe the issue to Claude and the troubleshoot skill will automatically activate to provide diagnosis.
-```
-/skill troubleshoot
-```
 
 ### Performance Issues
 
@@ -383,14 +383,16 @@ If searches seem slow:
 
 **Architecture Change (v5.4.0)**:
 - **Before**: 9 MCP tools (~2,500 tokens in tool definitions per session start)
-- **After**: 1 search skill (~250 tokens in frontmatter, full instructions loaded on-demand)
+- **After**: 1 mem-search skill (~250 tokens in frontmatter, full instructions loaded on-demand)
 - **Savings**: ~2,250 tokens per session start
 - **Migration**: Transparent - users don't need to change how they ask questions
 
+**v5.5.0 Enhancement**: Renamed from "search" to "mem-search" with improved effectiveness (67% → 100%) and enhanced triggers (44% → 85%).
+
 **How the Skill Works:**
 1. User asks a question about past work
-2. Claude recognizes the intent matches the search skill description
+2. Claude recognizes the intent matches the mem-search skill description
-3. Skill loads full instructions from `plugin/skills/search/SKILL.md`
+3. Skill loads full instructions from `plugin/skills/mem-search/SKILL.md`
 4. Skill uses `curl` to call HTTP API endpoints
 5. Results formatted and returned to Claude
 6. Claude presents results to user

package-lock.json

@@ -1,12 +1,12 @@
 {
   "name": "claude-mem",
-  "version": "5.4.1",
+  "version": "5.5.1",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "claude-mem",
-      "version": "5.4.1",
+      "version": "5.5.1",
       "license": "AGPL-3.0",
       "dependencies": {
         "@anthropic-ai/claude-agent-sdk": "^0.1.27",