claude-mem/docs/usage/search-tools.mdx

---
title: "Skill-Based Search"
description: "Query your project history with natural language"
---

# Skill-Based Search 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.

## 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.

**Simple Usage:**
- 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

**Benefits:**
- **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

| Operation               | Purpose                                      |
|-------------------------|----------------------------------------------|
| Search Observations     | Full-text search across observations         |
| Search Sessions         | Full-text search across session summaries    |
| Search Prompts          | Full-text search across raw user prompts     |
| By Concept              | Find observations tagged with concepts       |
| By File                 | Find observations referencing files          |
| By Type                 | Find observations by type                    |
| Recent Context          | Get recent session context                   |
| Timeline                | Get unified timeline around a specific point |
| Timeline by Query       | Search and get timeline context in one step  |
| API Help                | Get search API documentation                 |

## Example Queries

### Natural Language Queries

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

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

**Search Prompts:**
```
"When did I ask about authentication features?"
"Find all my requests about dark mode"
```

**Note**: Claude automatically translates your natural language queries into the appropriate search operations.

### 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

**Get timeline around a specific point:**
```
"What was happening when we implemented authentication?"
"Show me the context around that bug fix"
"What led to the decision to refactor the database?"
```

**Timeline by query:**
```
"Find when we added the viewer UI and show what happened around that time"
"Search for authentication work and show the timeline"
```

**Benefits:**
- 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

The search skill uses a progressive disclosure pattern to efficiently retrieve information:

### 1. Ask Naturally

Start with a natural language question:
```
"What bugs did we fix related to authentication?"
```

### 2. Claude Invokes Search Skill

Claude recognizes your intent and loads the search skill (~250 tokens for skill frontmatter).

### 3. Skill Uses HTTP API

The skill calls the appropriate HTTP endpoint (e.g., `/api/search/observations`) with the query.

### 4. Results Formatted

Results are formatted and presented to you, usually starting with an index/summary format.

### 5. Deep Dive if Needed

If you need more details, ask follow-up questions:
```
"Tell me more about observation #123"
"Show me the full details of that decision"
```

**Benefits of This Approach:**
- **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

You can refine searches using natural language filters:

### 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?"
```

**Note**: Claude translates your natural language into the appropriate API filters automatically.

## Under the Hood: HTTP API

The 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
- `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

These endpoints use FTS5 full-text search with support for:
- Boolean operators (AND, OR, NOT)
- Phrase searches
- Column-specific searches
- Date range filtering
- Project filtering

## Result Metadata

All results include rich 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

All search results include citations using the `claude-mem://` URI scheme:

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

These citations enable referencing specific historical context in your work.

## 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

| Format | Tokens per Result |
|--------|-------------------|
| Index  | 50-100            |
| Full   | 500-1000          |

**Example**:
- 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

Find what went wrong:
```
search_observations with query="error database connection" and type="bugfix"
```

### 2. Understanding Decisions

Review architectural choices:
```
find_by_type with type="decision" and format="index"
```

Then deep dive on specific decisions:
```
search_observations with query="[DECISION TITLE]" and format="full"
```

### 3. Code Archaeology

Find when a file was modified:
```
find_by_file with filePath="worker-service.ts"
```

### 4. Feature History

Track feature development:
```
search_sessions with query="authentication feature"
search_user_prompts with query="add authentication"
```

### 5. Learning from Past Work

Review refactoring patterns:
```
find_by_type with type="refactor" and limit=10
```

### 6. Context Recovery

Restore context after time away:
```
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:
   ```bash
   sqlite3 ~/.claude-mem/claude-mem.db "SELECT COUNT(*) FROM observations;"
   ```

2. Try broader natural language query:
   ```
   "Show me anything about authentication"  # Broader
   vs
   "Find exact JWT authentication implementation"  # Too specific
   ```

3. Ask without filters first:
   ```
   "What do we have about auth?"
   # Then narrow down
   "Show me auth-related decisions"
   ```

### Worker Service Not Running

If search isn't working, check the worker service:

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

Or use the troubleshooting skill:
```
/skill troubleshoot
```

### Performance Issues

If searches seem slow:
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

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

**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`
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](/architecture/overview) - System components
- [Database Schema](/architecture/database) - Understanding the data
- [Getting Started](/usage/getting-started) - Automatic operation