diff --git a/CLAUDE.md b/CLAUDE.md index ba59e99b..9ed7fadc 100644 --- a/CLAUDE.md +++ b/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 ` 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) diff --git a/README.md b/README.md index b464fb66..a578208e 100644 --- a/README.md +++ b/README.md @@ -17,7 +17,7 @@ License - Version + Version 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 -2. **Worker Service** - HTTP API on port 37777 with web viewer UI and 10 search endpoints, managed by PM2 -3. **SQLite Database** - Stores sessions, observations, summaries with FTS5 full-text search -4. **Search Skill** - Natural language queries with progressive disclosure (~2,250 token savings vs MCP) -5. **Chroma Vector Database** - Hybrid semantic + keyword search for intelligent context retrieval +1. **6 Lifecycle Hooks** - context-hook, user-message-hook, new-hook, save-hook, summary-hook, cleanup-hook +2. **Smart Install** - Cached dependency checker (pre-hook script, not a lifecycle hook) +3. **Worker Service** - HTTP API on port 37777 with web viewer UI and 10 search endpoints, managed by PM2 +4. **SQLite Database** - Stores sessions, observations, summaries with FTS5 full-text search +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: - -``` -/skill troubleshoot -``` +If you're experiencing issues, describe the problem to Claude and the troubleshoot skill will automatically activate to diagnose and provide fixes. **Common Issues:** diff --git a/docs/public/architecture/hooks.mdx b/docs/public/architecture/hooks.mdx index a824663f..327b24db 100644 --- a/docs/public/architecture/hooks.mdx +++ b/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 diff --git a/docs/public/architecture/overview.mdx b/docs/public/architecture/overview.mdx index be6329a2..683699d6 100644 --- a/docs/public/architecture/overview.mdx +++ b/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) -2. **Worker Service** - Process observations via Claude Agent SDK + HTTP API (10 search endpoints) -3. **Database Layer** - Store sessions and observations (SQLite + FTS5 + ChromaDB) -4. **Search Skill** - Skill-based search with progressive disclosure (v5.4.0+) -5. **Viewer UI** - Web-based real-time memory stream visualization +1. **Plugin Hooks** - Capture lifecycle events (6 hook files) +2. **Smart Install** - Cached dependency checker (pre-hook script, runs before context-hook) +3. **Worker Service** - Process observations via Claude Agent SDK + HTTP API (10 search endpoints) +4. **Database Layer** - Store sessions and observations (SQLite + FTS5 + ChromaDB) +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) -│ │ ├── smart-install.ts # Dependency check (cached) +│ ├── hooks/ # Hook implementations (6 hooks) │ │ ├── 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) -- **smart-install.js** - Cached dependency checker (only runs on version changes) +### 1. Plugin Hooks (6 Hooks) - **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 diff --git a/docs/public/architecture/search-architecture.mdx b/docs/public/architecture/search-architecture.mdx index 9907f424..a6218a66 100644 --- a/docs/public/architecture/search-architecture.mdx +++ b/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/` -2. Restart Claude Code session -3. Try explicit skill invocation: `/skill search` +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 diff --git a/docs/public/configuration.mdx b/docs/public/configuration.mdx index dd66fbfd..805abf58 100644 --- a/docs/public/configuration.mdx +++ b/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 diff --git a/docs/public/development.mdx b/docs/public/development.mdx index ece32843..5cf8ebba 100644 --- a/docs/public/development.mdx +++ b/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) -# In Claude Code, run: /skill version-bump -# This updates package.json, marketplace.json, and CLAUDE.md +# Manual version bump: +# 1. Update version in package.json +# 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 diff --git a/docs/public/hooks-architecture.mdx b/docs/public/hooks-architecture.mdx index 96021974..bf7a068e 100644 --- a/docs/public/hooks-architecture.mdx +++ b/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 diff --git a/docs/public/introduction.mdx b/docs/public/introduction.mdx index e53fdea1..465bbbf7 100644 --- a/docs/public/introduction.mdx +++ b/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 -2. **Worker Service** - HTTP API on port 37777 managed by PM2 -3. **SQLite Database** - Stores sessions, observations, summaries with FTS5 search -4. **9 MCP Search Tools** - Query historical context with citations -5. **Web Viewer UI** - Real-time visualization with SSE and infinite scroll +1. **6 Lifecycle Hooks** - SessionStart, UserPromptSubmit, PostToolUse, Stop, SessionEnd, UserMessage +2. **Smart Install** - Cached dependency checker (pre-hook script) +3. **Worker Service** - HTTP API on port 37777 managed by PM2 +4. **SQLite Database** - Stores sessions, observations, summaries with FTS5 search +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 diff --git a/docs/public/troubleshooting.mdx b/docs/public/troubleshooting.mdx index 614fb343..fb785587 100644 --- a/docs/public/troubleshooting.mdx +++ b/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. -``` -/skill troubleshoot -``` - -This skill will: +The troubleshoot 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. --- diff --git a/docs/public/usage/getting-started.mdx b/docs/public/usage/getting-started.mdx index 9d7845a9..9985fd1a 100644 --- a/docs/public/usage/getting-started.mdx +++ b/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 diff --git a/docs/public/usage/search-tools.mdx b/docs/public/usage/search-tools.mdx index 1294bc6d..f9915bfa 100644 --- a/docs/public/usage/search-tools.mdx +++ b/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: -``` -/skill troubleshoot -``` +Or describe the issue to Claude and the troubleshoot skill will automatically activate to provide diagnosis. ### 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 -3. Skill loads full instructions from `plugin/skills/search/SKILL.md` +2. Claude recognizes the intent matches the mem-search skill description +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 diff --git a/package-lock.json b/package-lock.json index 0d109a55..82a091c5 100644 --- a/package-lock.json +++ b/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",