​

Skill-Based Search Usage

​

How It Works

• Just ask naturally: “What did we do last session?”
• Claude recognizes the intent and invokes the search skill
• The skill uses HTTP API endpoints to query your memory
• Results are formatted and presented to you

• Token Efficient: ~250 tokens (skill frontmatter) vs ~2,500 tokens (MCP tool definitions)
• 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

​

Quick Reference

​

Example Queries

​

Natural Language Queries

"What bugs did we fix related to authentication?"
"Show me all decisions about the build system"
"Find refactoring work on the database"

"What did we learn about hooks?"
"What was accomplished in the API implementation?"
"Show me recent work on this project"

"When did I ask about authentication features?"
"Find all my requests about dark mode"

​

Search by File

"Show me everything related to worker-service.ts"
"What changes were made to migrations.ts?"
"Find all work on the database file"

​

Search by Concept

"Show observations tagged with architecture"
"Find all security-related observations"
"What patterns have we used?"

​

Search by Type

"Find all feature implementations"
"Show me all decisions and discoveries"
"What bugs have we fixed?"

​

Recent Context

"Show me what we've been working on"
"Get context from the last 5 sessions"
"What happened recently on this project?"

​

Timeline Queries

"What was happening when we implemented authentication?"
"Show me the context around that bug fix"
"What led to the decision to refactor the database?"

"Find when we added the viewer UI and show what happened around that time"
"Search for authentication work and show the timeline"

• See the complete narrative arc around key events
• All record types (observations, sessions, prompts) in chronological view
• Understand what was happening before and after important changes

​

Search Strategy

​

1. Ask Naturally

"What bugs did we fix related to authentication?"

​

2. Claude Invokes Search Skill

​

3. Skill Uses HTTP API

​

4. Results Formatted

​

5. Deep Dive if Needed

"Tell me more about observation #123"
"Show me the full details of that decision"

• Token Efficient: Only loads what you need, when you need it
• Natural: No syntax to learn
• Progressive: Start with overview, drill down as needed
• Automatic: Claude handles the search invocation

​

Advanced Filtering

​

Date Ranges

"What bugs did we fix in October?"
"Show me work from last week"
"Find decisions made between October 1-31"

​

Multiple Types

"Show me all decisions and features"
"Find bugfixes and refactorings"

​

Concepts

"Find database work related to architecture and performance"
"Show security observations"

​

File-Specific

"Show refactoring work that touched worker-service.ts"
"Find changes to auth files"

​

Project Filtering

"Show authentication work on my-app project"
"What have we done on this codebase?"

​

Under the Hood: HTTP API

• 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
• GET /api/context/recent - Get recent session context
• GET /api/context/timeline - Get timeline around specific point
• GET /api/timeline/by-query - Search + timeline in one call
• GET /api/search/help - API documentation

• Boolean operators (AND, OR, NOT)
• Phrase searches
• Column-specific searches
• Date range filtering
• Project filtering

​

Result Metadata

## JWT authentication decision

**Type**: decision
**Date**: 2025-10-21 14:23:45
**Concepts**: authentication, security, architecture
**Files Read**: src/auth/middleware.ts, src/utils/jwt.ts
**Files Modified**: src/auth/jwt-strategy.ts

**Narrative**:
Decided to implement JWT-based authentication instead of session-based
authentication for better scalability and stateless design...

**Facts**:
• JWT tokens expire after 1 hour
• Refresh tokens stored in httpOnly cookies
• Token signing uses RS256 algorithm
• Public keys rotated every 30 days

​

Citations

• claude-mem://observation/123 - Specific observation
• claude-mem://session/abc-456 - Specific session
• claude-mem://user-prompt/789 - Specific user prompt

​

Token Management

​

Token Efficiency Tips

1. Start with index format: ~50-100 tokens per result
2. Use small limits: Start with 3-5 results
3. Apply filters: Narrow results before searching
4. Paginate: Use offset to browse results in batches

​

Token Estimates

• 20 results in index format: ~1,000-2,000 tokens
• 20 results in full format: ~10,000-20,000 tokens

​

Common Use Cases

​

1. Debugging Issues

search_observations with query="error database connection" and type="bugfix"

​

2. Understanding Decisions

find_by_type with type="decision" and format="index"

search_observations with query="[DECISION TITLE]" and format="full"

​

3. Code Archaeology

find_by_file with filePath="worker-service.ts"

​

4. Feature History

search_sessions with query="authentication feature"
search_user_prompts with query="add authentication"

​

5. Learning from Past Work

find_by_type with type="refactor" and limit=10

​

6. Context Recovery

get_recent_context with limit=5
search_sessions with query="[YOUR PROJECT NAME]" and orderBy="date_desc"

​

Best Practices

1. Index first, full later: Always start with index format
2. Small limits: Start with 3-5 results to avoid token limits
3. Use filters: Narrow results before searching
4. Specific queries: More specific = better results
5. Review citations: Use citations to reference past decisions
6. Date filtering: Use date ranges for time-based searches
7. Type filtering: Use types to categorize searches
8. Concept tags: Use concepts for thematic searches

​

Troubleshooting

​

No Results Found

1. Check database has data:
   Copy

   sqlite3 ~/.claude-mem/claude-mem.db "SELECT COUNT(*) FROM observations;"
   

2. Try broader natural language query:
   Copy

   "Show me anything about authentication"  # Broader
   vs
   "Find exact JWT authentication implementation"  # Too specific
   

3. Ask without filters first:
   Copy

   "What do we have about auth?"
   # Then narrow down
   "Show me auth-related decisions"
   

​

Worker Service Not Running

pm2 list                    # Check worker status
npm run worker:restart      # Restart if needed
npm run worker:logs         # View logs

/skill troubleshoot

​

Performance Issues

1. Be more specific in your queries
2. Ask for recent work (naturally filters by date)
3. Specify the project you’re interested in
4. Ask for fewer results initially

​

Technical Details

• 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)
• Savings: ~2,250 tokens per session start
• Migration: Transparent - users don’t need to change how they ask questions

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
4. Skill uses curl to call HTTP API endpoints
5. Results formatted and returned to Claude
6. Claude presents results to user

​

Next Steps

• Architecture Overview - System components
• Database Schema - Understanding the data
• Getting Started - Automatic operation