---
title: "Memory Search"
description: "Search your project history with MCP tools"
---
# Memory Search with MCP Tools
claude-recall provides persistent memory across sessions through **4 MCP tools** that follow a token-efficient **3-layer workflow pattern**.
## Overview
Instead of fetching all historical data upfront (expensive), claude-recall uses a progressive disclosure approach:
1. **Search** → Get a compact index with IDs (~50-100 tokens/result)
2. **Timeline** → Get context around interesting results
3. **Get Observations** → Fetch full details ONLY for filtered IDs
This achieves **~10x token savings** compared to traditional RAG approaches.
## The 3-Layer Workflow
### Layer 1: Search (Index)
Start by searching to get a lightweight index of results:
```
search(query="authentication bug", type="bugfix", limit=10)
```
**Returns:** Compact table with IDs, titles, dates, types
**Cost:** ~50-100 tokens per result
**Purpose:** Survey what exists before fetching details
### Layer 2: Timeline (Context)
Get chronological context around specific observations:
```
timeline(anchor=<observation_id>, depth_before=3, depth_after=3)
```
Or search and get timeline in one step:
```
timeline(query="authentication", depth_before=2, depth_after=2)
```
**Returns:** Chronological view showing what was happening before/after
**Cost:** Variable, depends on depth
**Purpose:** Understand narrative arc and context
### Layer 3: Get Observations (Details)
Fetch full details only for relevant observations:
```
get_observations(ids=[123, 456, 789])
```
**Returns:** Complete observation details (narrative, facts, files, concepts)
**Cost:** ~500-1000 tokens per observation
**Purpose:** Deep dive on specific, validated items
### Why This Works
**Traditional Approach:**
- Fetch everything upfront: 20,000 tokens
- Relevance: ~10% (2,000 tokens actually useful)
- Waste: 18,000 tokens on irrelevant context
**3-Layer Approach:**
- Search index: 1,000 tokens (10 results)
- Timeline context: 500 tokens (around 2 key results)
- Fetch details: 1,500 tokens (3 observations)
- **Total: 3,000 tokens, 100% relevant**
## Available Tools
### `__IMPORTANT` - Workflow Documentation
Always visible reminder of the 3-layer workflow pattern. Helps Claude understand how to use the search tools efficiently.
**Usage:** Automatically shown, no need to invoke
### `search` - Search Memory Index
Search your memory and get a compact index with IDs.
**Parameters:**
- `query` - Full-text search query (supports AND, OR, NOT, phrase searches)
- `limit` - Maximum results (default: 20)
- `offset` - Skip first N results for pagination
- `type` - Filter by observation type (bugfix, feature, decision, discovery, refactor, change)
- `obs_type` - Filter by record type (observation, session, prompt)
- `project` - Filter by project name
- `dateStart` - Filter by start date (YYYY-MM-DD)
- `dateEnd` - Filter by end date (YYYY-MM-DD)
- `orderBy` - Sort order (date_desc, date_asc, relevance)
**Returns:** Compact index table with IDs, titles, dates, types
**Example:**
```
search(query="database migration", type="bugfix", limit=5, orderBy="date_desc")
```
### `timeline` - Get Chronological Context
Get a chronological view of observations around a specific point or query.
**Parameters:**
- `anchor` - Observation ID to center timeline around (optional if query provided)
- `query` - Search query to find anchor automatically (optional if anchor provided)
- `depth_before` - Number of observations before anchor (default: 3)
- `depth_after` - Number of observations after anchor (default: 3)
- `project` - Filter by project name
**Returns:** Chronological list showing what happened before/during/after
**Example:**
```
timeline(anchor=12345, depth_before=5, depth_after=5)
```
Or search-based:
```
timeline(query="implemented JWT auth", depth_before=3, depth_after=3)
```
### `get_observations` - Fetch Full Details
Fetch complete observation details by IDs. **Always batch multiple IDs in a single call for efficiency.**
**Parameters:**
- `ids` - Array of observation IDs (required)
- `orderBy` - Sort order (date_desc, date_asc)
- `limit` - Maximum observations to return
- `project` - Filter by project name
**Returns:** Complete observation details including narrative, facts, files, concepts
**Example:**
```
get_observations(ids=[123, 456, 789, 1011])
```
**Important:** Always batch IDs instead of making separate calls per observation.
## Common Use Cases
### Debugging Issues
**Scenario:** Find what went wrong with database connections
```
Step 1: search(query="error database connection", type="bugfix", limit=10)
→ Review index, identify observations #245, #312, #489
Step 2: timeline(anchor=312, depth_before=3, depth_after=3)
→ See what was happening around the fix
Step 3: get_observations(ids=[312, 489])
→ Get full details on relevant fixes
```
### Understanding Decisions
**Scenario:** Review architectural choices about authentication
```
Step 1: search(query="authentication", type="decision", limit=5)
→ Find decision observations
Step 2: get_observations(ids=[<relevant_ids>])
→ Get full decision rationale, trade-offs, facts
```
### Code Archaeology
**Scenario:** Find when a specific file was modified
```
Step 1: search(query="worker-service.ts", limit=20)
→ Get all observations mentioning that file
Step 2: timeline(query="worker-service.ts refactor", depth_before=2, depth_after=2)
→ See what led to and followed from the refactor
Step 3: get_observations(ids=[<specific_observation_ids>])
→ Get implementation details
```
### Feature History
**Scenario:** Track how a feature evolved
```
Step 1: search(query="dark mode", type="feature", orderBy="date_asc")
→ Chronological view of feature work
Step 2: timeline(anchor=<first_observation_id>, depth_after=10)
→ See the full development timeline
Step 3: get_observations(ids=[<key_milestones>])
→ Deep dive on critical implementation points
```
### Learning from Past Work
**Scenario:** Review refactoring patterns
```
Step 1: search(type="refactor", limit=10, orderBy="date_desc")
→ Recent refactoring work
Step 2: get_observations(ids=[<interesting_ids>])
→ Study the patterns and approaches used
```
### Context Recovery
**Scenario:** Restore context after time away from project
```
Step 1: search(query="project-name", limit=10, orderBy="date_desc")
→ See recent work
Step 2: timeline(anchor=<most_recent_id>, depth_before=10)
→ Understand what led to current state
Step 3: get_observations(ids=[<critical_observations>])
→ Refresh memory on key decisions
```
## Search Query Syntax
The `query` parameter supports SQLite FTS5 full-text search syntax:
### Boolean Operators
```
query="authentication AND JWT" # Both terms must appear
query="OAuth OR JWT" # Either term can appear
query="security NOT deprecated" # Exclude deprecated items
```
### Phrase Searches
```
query='"database migration"' # Exact phrase match
```
### Column-Specific Searches
```
query="title:authentication" # Search in title only
query="content:database" # Search in content only
query="concepts:security" # Search in concepts only
```
### Combining Operators
```
query='"user auth" AND (JWT OR session) NOT deprecated'
```
## Token Management
### Token Efficiency Best Practices
1. **Always start with search** - Get index first (~50-100 tokens/result)
2. **Use small limits** - Start with 3-5 results, increase if needed
3. **Filter before fetching** - Use type, date, project filters
4. **Batch get_observations** - Always group multiple IDs in one call
5. **Use timeline strategically** - Get context only when narrative matters
### Token Cost Estimates
| Operation | Tokens per Result |
|-----------|-------------------|
| search (index) | 50-100 |
| timeline (per observation) | 100-200 |
| get_observations (full details) | 500-1,000 |
**Example Comparison:**
**Inefficient:**
```
# Fetching 20 full observations upfront: 10,000-20,000 tokens
get_observations(ids=[1,2,3,4,5,6,7,8,9,10,11,12,13,14,15,16,17,18,19,20])
```
**Efficient:**
```
# Search index: ~1,000 tokens
search(query="bug fix", limit=20)
# Review IDs, identify 3 relevant observations
# Fetch only relevant: ~1,500-3,000 tokens
get_observations(ids=[5, 12, 18])
# Total: 2,500-4,000 tokens (vs 10,000-20,000)
```
## Advanced Filtering
### Date Ranges
```
search(
query="performance optimization",
dateStart="2025-10-01",
dateEnd="2025-10-31"
)
```
### Multiple Types
For observations of multiple types, make multiple searches or use broader query:
```
search(query="database", type="bugfix", limit=10)
search(query="database", type="feature", limit=10)
```
### Project-Specific
```
search(query="API", project="my-app", limit=15)
```
### Pagination
```
# First page
search(query="refactor", limit=10, offset=0)
# Second page
search(query="refactor", limit=10, offset=10)
# Third page
search(query="refactor", limit=10, offset=20)
```
## Result Metadata
All observations include rich metadata:
- **ID** - Unique observation identifier
- **Type** - bugfix, feature, decision, discovery, refactor, change
- **Date** - When the work occurred
- **Title** - Concise description
- **Concepts** - Tagged themes (e.g., security, performance, architecture)
- **Files Read** - Files examined during work
- **Files Modified** - Files changed during work
- **Narrative** - Story of what happened and why
- **Facts** - Key factual points (decisions made, patterns used, metrics)
## Troubleshooting
### No Results Found
1. **Broaden your search:**
```
# Too specific
search(query="JWT authentication implementation with RS256")
# Better
search(query="authentication")
```
2. **Check database has data:**
```bash
curl "http://localhost:37777/api/search?query=test"
```
3. **Try without filters:**
```
# Remove type/date filters to see if data exists
search(query="your-search-term")
```
### IDs Not Found in get_observations
**Error:** "Observation IDs not found: [123, 456]"
**Causes:**
- IDs from different project (use `project` parameter)
- IDs were deleted
- Typo in ID numbers
**Solution:**
```
# Verify IDs exist
search(query="<related-search>")
# Use correct project filter
get_observations(ids=[123, 456], project="correct-project-name")
```
### Token Limit Errors
**Error:** Response exceeds token limits
**Solution:** Use the 3-layer workflow to reduce upfront costs:
```
# Instead of fetching 50 full observations:
# get_observations(ids=[1,2,3,...,50]) # 25,000-50,000 tokens!
# Do this:
search(query="<your-query>", limit=50) # ~2,500-5,000 tokens
# Review index, identify 5 relevant observations
get_observations(ids=[<5-most-relevant>]) # ~2,500-5,000 tokens
# Total: 5,000-10,000 tokens (50-80% savings)
```
### Search Performance
If searches seem slow:
1. Be more specific in queries (helps FTS5 index)
2. Use date range filters to narrow scope
3. Specify project filter when possible
4. Use smaller limit values
## Best Practices
1. **Index First, Details Later** - Always start with search to survey options
2. **Filter Before Fetching** - Use search parameters to narrow results
3. **Batch ID Fetches** - Group multiple IDs in one get_observations call
4. **Use Timeline for Context** - When narrative matters, timeline shows the story
5. **Specific Queries** - More specific = better relevance
6. **Small Limits Initially** - Start with 3-5 results, expand if needed
7. **Review Before Deep Dive** - Check index before fetching full details
## Technical Details
**Architecture:** MCP tools are a thin wrapper over the Worker HTTP API (localhost:37777). The MCP server translates tool calls into HTTP requests to the worker service, which handles all business logic, database queries, and Chroma vector search.
**MCP Server:** Located at `~/.claude/plugins/marketplaces/nhevers/extension/runtime/search-server.cjs`
**Worker Service:** Express API on port 37777, managed by Bun
**Database:** SQLite FTS5 full-text search on `~/.claude-recall/claude-recall.db`
**Vector Search:** Chroma embeddings for semantic search (underlying implementation)
## Next Steps
- [Progressive Disclosure](/progressive-disclosure) - Philosophy behind 3-layer workflow
- [Architecture Overview](/architecture/overview) - System components
- [Database Schema](/architecture/database) - Understanding the data structure
- [Claude Desktop Setup](/usage/claude-desktop) - Installation and configuration
