Alex Newman
0475a57fb1
- Implemented a new skill-based search approach, replacing MCP search tools to reduce session start context from ~2,500 tokens to ~250 tokens. - Added 10 new HTTP API endpoints to the worker service for various search functionalities. - Created a new search skill with detailed instructions and examples for users. - Removed MCP search server references and updated documentation to reflect the new skill-based approach. - Enhanced context handling in the context hook to conditionally display the most recent summary based on observations. - Introduced comprehensive documentation for Agent Skills, including creation, management, and best practices.
4.2 KiB
Plan: Migrate to Skill-Based Search (Deprecate MCP)
Goal
Replace MCP search tools with a skill-based approach, reducing session start context from ~2,500 tokens to ~250 tokens. Clean migration, no toggles.
Implementation Steps
- Add HTTP API Endpoints to Worker Service
File: src/services/worker-service.ts
Add 10 new routes that wrap existing SessionSearch methods:
- GET /api/search/observations?query=...&format=index&limit=20&project=...
- GET /api/search/sessions?query=...&format=index&limit=20
- GET /api/search/prompts?query=...&format=index&limit=20
- GET /api/search/by-concept?concept=discovery&format=index&limit=5
- GET /api/search/by-file?filePath=...&format=index&limit=10
- GET /api/search/by-type?type=bugfix&format=index&limit=10
- GET /api/context/recent?project=...&limit=3
- GET /api/context/timeline?anchor=123&depth_before=10&depth_after=10
- GET /api/timeline/by-query?query=...&mode=auto&depth_before=10&depth_after=10
- GET /api/search/help - Returns available endpoints and usage docs
All endpoints return JSON. Skill parses and formats for readability.
- Create Search Skill
File: plugin/skills/search/SKILL.md
Frontmatter:
name: search description: Search claude-mem persistent memory for past sessions, observations, bugs fixed, features implemented, decisions made, code changes, and previous work. Use when answering questions about history, finding past decisions, or researching previous implementations.
Content: Instructions for all 9 search types using curl to call HTTP endpoints, formatting guidelines, common workflows.
- Remove MCP Search Server
Files to modify:
- Remove plugin/.mcp.json entry for claude-mem-search
- Keep src/servers/search-server.ts for reference but don't build it
- Update scripts/build-plugin.js to skip building search-server.mjs
- Archive search-server implementation (don't delete, for reference)
- Update Documentation
File: CLAUDE.md
Remove MCP search references, add skill search explanation:
- Token savings: ~2,250 tokens per session
- How skill auto-invokes (model-driven, not user-driven)
- Available search operations
- Examples of triggering searches
- Add Migration Notice
File: CHANGELOG.md or release notes
Document the breaking change:
v5.4.0 - Skill-Based Search Migration
BREAKING CHANGE: MCP search tools have been replaced with a skill-based approach.
What changed:
- Removed 9 MCP search tools (search_observations, search_sessions, etc.)
- Added
searchskill that provides the same functionality - Reduced session start context by ~2,250 tokens
Migration: None required. Claude automatically uses the search skill when needed. The skill provides the same search capabilities with better token efficiency.
Why: Skill-based search uses progressive disclosure (~250 tokens for frontmatter) instead of loading all 9 tool definitions (~2,500 tokens) on every session start.
- Testing Checklist
- All 10 HTTP endpoints return correct data
- Skill auto-invokes when asking about past work
- Skill successfully calls endpoints via curl
- Skill formats results as readable markdown
- Worker restart updates endpoints
- Skill distributed correctly with plugin
- No MCP search server registered
- Session start context reduced by ~2,250 tokens
Token Impact
- Before: ~2,500 tokens (9 MCP tool definitions)
- After: ~250 tokens (skill frontmatter only)
- Savings: ~2,250 tokens per session start
User Experience
New behavior:
- User: "What bug did we fix last session?"
- Claude sees skill description matches → invokes search skill
- Skill loads full instructions → uses curl to call HTTP API → formats results
- User sees formatted answer
No user action required: Migration is transparent, searches work automatically.
Build & Deploy
npm run build # Builds skill, skips MCP server npm run sync-marketplace # Syncs plugin with skill npm run worker:restart # Restart worker with new HTTP endpoints
Rollout
- Ship as breaking change in v5.4.0
- Update plugin marketplace listing
- All users get automatic token savings on update
- Archive MCP search implementation for reference