thedotmack/claude-mem v5.4.0

v5.4.0: Skill-Based Search Migration & Progressive Disclosure

on GitHub

v5.4.0 - Skill-Based Search Migration & Progressive Disclosure (2025-11-09)

⚠️ BREAKING CHANGE: MCP Search Tools Removed

Migration: None required. Claude automatically uses the search skill when needed.

🔍 Major Feature: Skill-Based Search Architecture

Token Savings: ~2,250 tokens per session start (90% reduction)

What Changed:

• 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)
• User Experience: Identical - just ask naturally about past work

✨ Improvements

Progressive Disclosure Pattern:

• Skill frontmatter (~250 tokens) loads at session start
• Full instructions (~2,500 tokens) load only when skill is invoked
• HTTP API endpoints replace MCP protocol
• No user action required - migration is transparent

Natural Language Queries:

"What bugs did we fix last session?"
"How did we implement authentication?"
"What changes were made to worker-service.ts?"
"Show me recent work on this project"

🆕 Added

10 New HTTP Search API Endpoints in worker service:

• GET /api/search/observations - Full-text search observations
• GET /api/search/sessions - Full-text search session summaries
• GET /api/search/prompts - Full-text search user prompts
• GET /api/search/by-concept - Find observations by concept tag
• GET /api/search/by-file - Find work related to specific files
• GET /api/search/by-type - Find observations by type (bugfix, feature, etc.)
• GET /api/context/recent - Get recent session context
• GET /api/context/timeline - Get timeline around specific point in time
• GET /api/timeline/by-query - Search + timeline in one call
• GET /api/search/help - API documentation

Search Skill (plugin/skills/search/SKILL.md):

• Auto-invoked when users ask about past work, decisions, or history
• Comprehensive documentation with usage examples and workflows
• Format guidelines for presenting search results
• 12 operation files with detailed instructions

🗑️ Removed

MCP Search Server (deprecated):

• Removed claude-mem-search from plugin/.mcp.json
• Build script no longer compiles search-server.mjs
• Source file kept for reference: src/servers/search-server.ts
• All 9 MCP tools replaced by equivalent HTTP API endpoints

📚 Documentation

Comprehensive Updates:

• README.md: Updated version badge, What's New, and search section
• docs/usage/search-tools.mdx: Complete rewrite for skill-based approach
• docs/architecture/mcp-search.mdx → search-architecture.mdx: New architecture doc
• docs/architecture/overview.mdx: Updated components and search pipeline
• docs/usage/getting-started.mdx: Added skill-based search section
• docs/configuration.mdx: Updated search configuration
• docs/introduction.mdx: Updated key features

🔧 Technical Details

How It Works:

1. User asks: "What did we do last session?"
2. Claude recognizes intent → invokes search skill
3. Skill loads full instructions from SKILL.md
4. Skill uses curl to call HTTP API endpoint
5. Results formatted and returned to Claude
6. Claude presents results to user

Benefits:

• Token Efficient: Only loads what you need, when you need it
• Natural: No syntax to learn, just ask questions
• Progressive: Start with overview, drill down as needed
• Flexible: HTTP API can be called from skills, MCP tools, or other clients

🐛 Migration Notes

For Users:

• ✅ No action required - migration is transparent
• ✅ Same questions work - natural language queries identical
• ✅ Invisible change - only notice better performance

For Developers:

• ⚠️ MCP search server deprecated (source kept for reference)
• ✅ New implementation: Skill files + HTTP endpoints
• ✅ Build/sync workflow unchanged

📦 Installation

/plugin marketplace add thedotmack/claude-mem
/plugin install claude-mem

Restart Claude Code to start using v5.4.0.

🔗 Resources

• Documentation: https://github.com/thedotmack/claude-mem/tree/main/docs
• Issues: https://github.com/thedotmack/claude-mem/issues
• CHANGELOG: https://github.com/thedotmack/claude-mem/blob/main/CHANGELOG.md

Full Changelog: v5.3.0...v5.4.0