airkjw/claude-mem
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Align user-facing documentation with v5.5.1 codebase state (#99)

Browse Source 
* Initial plan

* Update documentation to reflect v5.5.1 state and mem-search skill

Co-authored-by: thedotmack <683968+thedotmack@users.noreply.github.com>

* Update hooks documentation to clarify 6 hooks + pre-hook architecture

Co-authored-by: thedotmack <683968+thedotmack@users.noreply.github.com>

* Complete documentation alignment with mem-search skill naming

Co-authored-by: thedotmack <683968+thedotmack@users.noreply.github.com>

* Fix remaining old skill path references in troubleshooting docs

Co-authored-by: thedotmack <683968+thedotmack@users.noreply.github.com>

* Documentation alignment complete - all tests pass

Co-authored-by: thedotmack <683968+thedotmack@users.noreply.github.com>

* Fix hallucinated /skill command references - skills are auto-invoked

Co-authored-by: thedotmack <683968+thedotmack@users.noreply.github.com>

---------

Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com>
Co-authored-by: thedotmack <683968+thedotmack@users.noreply.github.com>
This commit is contained in:
Copilot
2025-11-12 14:59:04 -05:00
committed by GitHub
parent 1c9da73d5f
commit 7bdf6dbfe1
13 changed files with 207 additions and 133 deletions
Download Patch File Download Diff File Expand all files Collapse all files
CLAUDE.md
+50 -7
View File
@@ -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
+22 -17
View File
@@ -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
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:**
docs/public/architecture/hooks.mdx
+10 -6
View File
@@ -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
+28 -18
View File
@@ -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
docs/public/architecture/search-architecture.mdx
+23 -15
View File
@@ -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
docs/public/configuration.mdx
+4 -4
View File
@@ -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
+7 -4
View File
@@ -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
docs/public/hooks-architecture.mdx
+16 -14
View File
@@ -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
+20 -19
View File
@@ -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
<CardGroup cols={2}>
docs/public/troubleshooting.mdx
+3 -7
View File
@@ -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.
---
docs/public/usage/getting-started.mdx
+4 -4
View File
@@ -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
+18 -16
View File
@@ -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
package-lock.json
Generated
+2 -2
View File
@@ -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",