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

---
title: "MCP Search Tools"
description: "Query your project history with 9 specialized search tools"
---

# MCP Search Tools Usage

Once claude-mem is installed as a plugin, 9 search tools become available in your Claude Code sessions for querying project history.

## Quick Reference

| Tool                    | Purpose                                      |
|-------------------------|----------------------------------------------|
| search_observations     | Full-text search across observations         |
| search_sessions         | Full-text search across session summaries    |
| search_user_prompts     | Full-text search across raw user prompts     |
| find_by_concept         | Find observations tagged with concepts       |
| find_by_file            | Find observations referencing files          |
| find_by_type            | Find observations by type                    |
| get_recent_context      | Get recent session context                   |
| get_context_timeline    | Get unified timeline around a specific point |
| get_timeline_by_query   | Search and get timeline context in one step  |

## Example Queries

### search_observations

Find all decisions about the build system:
```
Use search_observations to find all decisions about the build system
```

Find bugs related to authentication:
```
search_observations with query="authentication" and type="bugfix"
```

Search for refactoring work:
```
search_observations with query="refactor database" and type="refactor"
```

### search_sessions

Find what we learned about hooks:
```
Use search_sessions to find what we learned about hooks
```

Search for completed work on the API:
```
search_sessions with query="API implementation"
```

### search_user_prompts

Find when user asked about authentication:
```
search_user_prompts with query="authentication feature"
```

Trace user requests for a specific feature:
```
search_user_prompts with query="dark mode"
```

**Benefits**:
- See exactly what the user asked for (vs what was implemented)
- Detect patterns in repeated requests
- Debug miscommunications between user intent and implementation

### find_by_file

Show everything related to worker-service.ts:
```
Use find_by_file to show me everything related to worker-service.ts
```

Find all work on the database migration file:
```
find_by_file with filePath="migrations.ts"
```

### find_by_concept

Show observations tagged with 'architecture':
```
Use find_by_concept to show observations tagged with 'architecture'
```

Find all 'security' related observations:
```
find_by_concept with concept="security"
```

### find_by_type

Find all feature implementations:
```
find_by_type with type="feature"
```

Find all decisions and discoveries:
```
find_by_type with type=["decision", "discovery"]
```

### get_recent_context

Get the last 5 sessions for context:
```
get_recent_context with limit=5
```

Get recent context for debugging:
```
Use get_recent_context to show me what we've been working on
```

### get_context_timeline

Get a unified timeline of context around a specific point in time. This tool interleaves observations, sessions, and user prompts chronologically to show what was happening before and after a specific moment.

**Anchor by observation ID:**
```
get_context_timeline with anchor=12345 and depth_before=10 and depth_after=10
```

**Anchor by session ID:**
```
get_context_timeline with anchor="S123" and depth_before=5 and depth_after=5
```

**Anchor by ISO timestamp:**
```
get_context_timeline with anchor="2025-10-21T14:30:00Z" and depth_before=15 and depth_after=15
```

**Use cases:**
- Understand what was happening when a specific observation occurred
- See the full context around a bug fix or decision
- Trace the events leading up to and following a specific change
- View chronological sequence of related work

**Benefits:**
- All record types (observations, sessions, prompts) in one chronological view
- Configurable depth before/after anchor point
- Flexible anchoring by ID or timestamp
- See the complete narrative arc around key events

### get_timeline_by_query

Search for observations using natural language and get timeline context around the best match. This combines search + timeline into a single operation for faster context discovery.

**Auto mode (default):**
```
get_timeline_by_query with query="authentication implementation"
```
Automatically uses the top search result as timeline anchor and returns surrounding context.

**Interactive mode:**
```
get_timeline_by_query with query="authentication" and mode="interactive" and limit=5
```
Shows top 5 search results for you to manually choose which to use as timeline anchor.

**Customize timeline depth:**
```
get_timeline_by_query with query="bug fix" and depth_before=20 and depth_after=10
```

**Use cases:**
- Quick context discovery: "What was happening when we implemented X?"
- Investigate issues: Find a bug fix and see what led to it
- Decision archaeology: Search for a decision and understand the context
- Feature timeline: See the complete story of a feature implementation

**Benefits:**
- Single-step operation (no need to search, then timeline separately)
- Auto mode provides instant context
- Interactive mode gives you control over anchor selection
- Natural language search makes it easy to find relevant moments

## Search Strategy

### 1. Start with Index Format

**Always use index format first** to get an overview:

```
search_observations with query="authentication" and format="index"
```

**Why?**
- Index format uses ~10x fewer tokens than full format
- See titles, dates, and sources to identify relevant results
- Avoid hitting MCP token limits

### 2. Review Results

Look at the index results to identify items of interest:

```
1. [decision] Implement JWT authentication
   Date: 2025-10-21 14:23:45
   Source: claude-mem://observation/123

2. [feature] Add user authentication endpoints
   Date: 2025-10-21 13:15:22
   Source: claude-mem://observation/124

3. [bugfix] Fix authentication token expiry
   Date: 2025-10-20 16:45:30
   Source: claude-mem://observation/125
```

### 3. Deep Dive with Full Format

Only use full format for specific items:

```
search_observations with query="JWT authentication" and format="full" and limit=3
```

### 4. Use Filters to Narrow Results

Combine filters for precise searches:

```
search_observations with query="authentication" and type="decision" and dateRange={start: "2025-10-20", end: "2025-10-21"}
```

## Advanced Filtering

### Date Ranges

Search within specific time periods:

```json
{
  "dateRange": {
    "start": "2025-10-01",
    "end": "2025-10-31"
  }
}
```

Or use epoch timestamps:

```json
{
  "dateRange": {
    "start": 1729449600,
    "end": 1732128000
  }
}
```

### Multiple Types

Search across multiple observation types:

```
find_by_type with type=["decision", "feature", "refactor"]
```

### Multiple Concepts

Search observations with specific concepts:

```
search_observations with query="database" and concepts=["architecture", "performance"]
```

### File Filtering

Search observations that touched specific files:

```
search_observations with query="refactor" and files="worker-service.ts"
```

### Project Filtering

Search within specific projects:

```
search_observations with query="authentication" and project="my-app"
```

## FTS5 Query Syntax

The `query` parameter supports SQLite FTS5 full-text search syntax:

### Simple Queries
```
"authentication"           # Single word
"error handling"           # Multiple words (OR)
```

### Boolean Operators
```
"error" AND "handling"     # Both terms required
"bug" OR "fix"             # Either term
"bug" NOT "feature"        # First term, not second
```

### Phrase Searches
```
"'exact phrase'"           # Exact phrase match
```

### Column Searches
```
title:"authentication"     # Search specific column
narrative:"bug fix"        # Search narrative field
```

## 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 query:
   ```
   search_observations with query="authentication"  # Good
   vs
   search_observations with query="'exact JWT authentication implementation'"  # Too specific
   ```

3. Remove filters:
   ```
   # Start broad
   search_observations with query="auth"

   # Then add filters
   search_observations with query="auth" and type="decision"
   ```

### Token Limit Errors

1. Use index format:
   ```
   search_observations with query="..." and format="index"
   ```

2. Reduce limit:
   ```
   search_observations with query="..." and limit=3
   ```

3. Use pagination:
   ```
   # First page
   search_observations with query="..." and limit=5 and offset=0

   # Second page
   search_observations with query="..." and limit=5 and offset=5
   ```

### Search Too Slow

1. Use more specific queries
2. Add date range filters
3. Add type/concept filters
4. Reduce result limit

## Next Steps

- [MCP Search Architecture](/architecture/mcp-search) - Technical details
- [Database Schema](/architecture/database) - Understanding the data
- [Getting Started](/usage/getting-started) - Automatic operation