Replace search skill with mem-search (#91)
* feat: add mem-search skill with progressive disclosure architecture Add comprehensive mem-search skill for accessing claude-mem's persistent cross-session memory database. Implements progressive disclosure workflow and token-efficient search patterns. Features: - 12 search operations (observations, sessions, prompts, by-type, by-concept, by-file, timelines, etc.) - Progressive disclosure principles to minimize token usage - Anti-patterns documentation to guide LLM behavior - HTTP API integration for all search functionality - Common workflows with composition examples Structure: - SKILL.md: Entry point with temporal trigger patterns - principles/: Progressive disclosure + anti-patterns - operations/: 12 search operation files 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com> * docs: add CHANGELOG entry for mem-search skill Document mem-search skill addition in Unreleased section with: - 100% effectiveness compliance metrics - Comparison to previous search skill implementation - Progressive disclosure architecture details - Reference to audit report documentation 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com> * docs: add mem-search skill audit report Add comprehensive audit report validating mem-search skill against Anthropic's official skill-creator documentation. Report includes: - Effectiveness metrics comparison (search vs mem-search) - Critical issues analysis for production readiness - Compliance validation across 6 key dimensions - Reference implementation guidance Result: mem-search achieves 100% compliance vs search's 67% 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com> * feat: Add comprehensive search architecture analysis document - Document current state of dual search architectures (HTTP API and MCP) - Analyze HTTP endpoints and MCP search server architectures - Identify DRY violations across search implementations - Evaluate the use of curl as the optimal approach for search - Provide architectural recommendations for immediate and long-term improvements - Outline action plan for cleanup, feature parity, DRY refactoring * refactor: Remove deprecated search skill documentation and operations * refactor: Reorganize documentation into public and context directories Changes: - Created docs/public/ for Mintlify documentation (.mdx files) - Created docs/context/ for internal planning and implementation docs - Moved all .mdx files and assets to docs/public/ - Moved all internal .md files to docs/context/ - Added CLAUDE.md to both directories explaining their purpose - Updated docs.json paths to work with new structure Benefits: - Clear separation between user-facing and internal documentation - Easier to maintain Mintlify docs in dedicated directory - Internal context files organized separately 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com> * Enhance session management and continuity in hooks - Updated new-hook.ts to clarify session_id threading and idempotent session creation. - Modified prompts.ts to require claudeSessionId for continuation prompts, ensuring session context is maintained. - Improved SessionStore.ts documentation on createSDKSession to emphasize idempotent behavior and session connection. - Refined SDKAgent.ts to detail continuation prompt logic and its reliance on session.claudeSessionId for unified session handling. --------- Co-authored-by: Claude <noreply@anthropic.com> Co-authored-by: Alex Newman <thedotmack@gmail.com>
This commit is contained in:
basher83
@@ -0,0 +1,176 @@
|
||||
# Anti-Pattern Catalogue
|
||||
|
||||
Common mistakes to avoid when using the HTTP search API. These anti-patterns address LLM training biases and prevent token-wasting behaviors.
|
||||
|
||||
## Anti-Pattern 1: Skipping Index Format
|
||||
|
||||
**The Mistake:**
|
||||
```bash
|
||||
# ❌ Bad: Jump straight to full format
|
||||
curl -s "http://localhost:37777/api/search/observations?query=authentication&format=full&limit=20"
|
||||
```
|
||||
|
||||
**Why It's Wrong:**
|
||||
- 20 × 750 tokens = 15,000 tokens
|
||||
- May hit MCP token limits
|
||||
- 99% wasted on irrelevant results
|
||||
|
||||
**The Correction:**
|
||||
```bash
|
||||
# ✅ Good: Start with index, review, then request full selectively
|
||||
curl -s "http://localhost:37777/api/search/observations?query=authentication&format=index&limit=5"
|
||||
# Review results, identify relevant items
|
||||
curl -s "http://localhost:37777/api/search/observations?query=authentication&format=full&limit=1&offset=2"
|
||||
```
|
||||
|
||||
**What It Teaches:**
|
||||
Progressive disclosure isn't optional - it's essential for scale.
|
||||
|
||||
**LLM Behavior Insight:**
|
||||
LLMs trained on code examples may have seen `format=full` as "more complete" and default to it.
|
||||
|
||||
---
|
||||
|
||||
## Anti-Pattern 2: Over-Requesting Results
|
||||
|
||||
**The Mistake:**
|
||||
```bash
|
||||
# ❌ Bad: Request limit=20 without reviewing index first
|
||||
curl -s "http://localhost:37777/api/search/observations?query=auth&format=index&limit=20"
|
||||
```
|
||||
|
||||
**Why It's Wrong:**
|
||||
- Most of 20 results will be irrelevant
|
||||
- Wastes tokens and time
|
||||
- Overwhelms review process
|
||||
|
||||
**The Correction:**
|
||||
```bash
|
||||
# ✅ Good: Start small, paginate if needed
|
||||
curl -s "http://localhost:37777/api/search/observations?query=auth&format=index&limit=5"
|
||||
# If needed, paginate:
|
||||
curl -s "http://localhost:37777/api/search/observations?query=auth&format=index&limit=5&offset=5"
|
||||
```
|
||||
|
||||
**What It Teaches:**
|
||||
Start small (limit=3-5), review, paginate if needed.
|
||||
|
||||
**LLM Behavior Insight:**
|
||||
LLMs may think "more results = more thorough" without considering relevance.
|
||||
|
||||
---
|
||||
|
||||
## Anti-Pattern 3: Ignoring Tool Specialization
|
||||
|
||||
**The Mistake:**
|
||||
```bash
|
||||
# ❌ Bad: Use generic search for everything
|
||||
curl -s "http://localhost:37777/api/search/observations?query=bugfix&format=index&limit=10"
|
||||
```
|
||||
|
||||
**Why It's Wrong:**
|
||||
- Specialized tools (by-type, by-concept, by-file) are more efficient
|
||||
- Generic search mixes all result types
|
||||
- Misses filtering optimization
|
||||
|
||||
**The Correction:**
|
||||
```bash
|
||||
# ✅ Good: Use specialized endpoint when applicable
|
||||
curl -s "http://localhost:37777/api/search/by-type?type=bugfix&format=index&limit=10"
|
||||
```
|
||||
|
||||
**What It Teaches:**
|
||||
The decision tree exists for a reason - follow it.
|
||||
|
||||
**LLM Behavior Insight:**
|
||||
LLMs may gravitate toward "general purpose" tools to avoid decision-making.
|
||||
|
||||
---
|
||||
|
||||
## Anti-Pattern 4: Loading Full Context Prematurely
|
||||
|
||||
**The Mistake:**
|
||||
```bash
|
||||
# ❌ Bad: Request full format before understanding what's relevant
|
||||
curl -s "http://localhost:37777/api/search/observations?query=database&format=full&limit=10"
|
||||
```
|
||||
|
||||
**Why It's Wrong:**
|
||||
- Can't filter relevance without seeing index first
|
||||
- Wastes tokens on irrelevant full details
|
||||
- 10 × 750 = 7,500 tokens for potentially zero useful results
|
||||
|
||||
**The Correction:**
|
||||
```bash
|
||||
# ✅ Good: Index first to identify relevance
|
||||
curl -s "http://localhost:37777/api/search/observations?query=database&format=index&limit=10"
|
||||
# Identify relevant: #1234 and #1250
|
||||
curl -s "http://localhost:37777/api/search/observations?query=database+1234&format=full&limit=1"
|
||||
curl -s "http://localhost:37777/api/search/observations?query=database+1250&format=full&limit=1"
|
||||
```
|
||||
|
||||
**What It Teaches:**
|
||||
Filtering is a prerequisite for expansion.
|
||||
|
||||
**LLM Behavior Insight:**
|
||||
LLMs may try to "get everything at once" to avoid multiple tool calls.
|
||||
|
||||
---
|
||||
|
||||
## Anti-Pattern 5: Not Using Timeline Tools
|
||||
|
||||
**The Mistake:**
|
||||
```bash
|
||||
# ❌ Bad: Search for individual observations separately
|
||||
curl -s "http://localhost:37777/api/search/observations?query=before+deployment"
|
||||
curl -s "http://localhost:37777/api/search/observations?query=during+deployment"
|
||||
curl -s "http://localhost:37777/api/search/observations?query=after+deployment"
|
||||
```
|
||||
|
||||
**Why It's Wrong:**
|
||||
- Misses context around events
|
||||
- Inefficient (N searches vs 1 timeline)
|
||||
- Temporal relationships lost
|
||||
|
||||
**The Correction:**
|
||||
```bash
|
||||
# ✅ Good: Use timeline tool for contextual investigation
|
||||
curl -s "http://localhost:37777/api/timeline/by-query?query=deployment&depth_before=10&depth_after=10"
|
||||
```
|
||||
|
||||
**What It Teaches:**
|
||||
Tool composition - some tools are designed to work together.
|
||||
|
||||
**LLM Behavior Insight:**
|
||||
LLMs may not naturally discover tool composition patterns.
|
||||
|
||||
---
|
||||
|
||||
## Why These Anti-Patterns Matter
|
||||
|
||||
**Addresses LLM Training Bias:**
|
||||
LLMs default to "load everything" behavior from web scraping training data where thoroughness was rewarded.
|
||||
|
||||
**Teaches Protocol Awareness:**
|
||||
HTTP APIs and MCP have real token limits that can break the system.
|
||||
|
||||
**Prevents User Frustration:**
|
||||
Token limit errors confuse users and break workflows.
|
||||
|
||||
**Builds Good Habits:**
|
||||
Anti-patterns teach the "why" behind best practices.
|
||||
|
||||
**Makes Implicit Explicit:**
|
||||
Surfaces mental models that experienced users internalize but novices miss.
|
||||
|
||||
---
|
||||
|
||||
## What Happens If These Are Ignored
|
||||
|
||||
- **No progressive disclosure**: Every search loads limit=20 in full format → token exhaustion
|
||||
- **Over-requesting**: 15,000 token searches for 2 relevant results
|
||||
- **Wrong tool**: Generic search when specialized filters would be 10x faster
|
||||
- **Premature expansion**: Load full details before knowing relevance
|
||||
- **Missing composition**: Single-tool thinking, missing powerful multi-step workflows
|
||||
|
||||
**Bottom Line:** These anti-patterns waste 5-10x more tokens than necessary and frequently cause system failures.
|
||||
Reference in New Issue
Block a user