​

Memory Search with MCP Tools

​

Overview

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

​

The 3-Layer Workflow

​

Layer 1: Search (Index)

search(query="authentication bug", type="bugfix", limit=10)

​

Layer 2: Timeline (Context)

timeline(anchor=<observation_id>, depth_before=3, depth_after=3)

timeline(query="authentication", depth_before=2, depth_after=2)

​

Layer 3: Get Observations (Details)

get_observations(ids=[123, 456, 789])

​

Why This Works

• Fetch everything upfront: 20,000 tokens
• Relevance: ~10% (2,000 tokens actually useful)
• Waste: 18,000 tokens on irrelevant context

• 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 - Workflow Documentation

​

search - Search Memory Index

• query - What to look for, in plain words: matched by meaning first, then by keywords (see How the query is matched)
• limit - Maximum results (default: 20)
• offset - Skip first N results for pagination
• type - Record category: observations, sessions or prompts (default: all). Any other value is treated as an observation type, like obs_type
• obs_type - Filter observations by type (bugfix, feature, decision, discovery, refactor, change); comma-separated for several
• 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)

search(query="database migration", type="bugfix", limit=5, orderBy="date_desc")

​

timeline - Get Chronological Context

• 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

timeline(anchor=12345, depth_before=5, depth_after=5)

timeline(query="implemented JWT auth", depth_before=3, depth_after=3)

​

get_observations - Fetch Full Details

• ids - Array of observation IDs (required)
• orderBy - Sort order (date_desc, date_asc)
• limit - Maximum observations to return
• project - Filter by project name

get_observations(ids=[123, 456, 789, 1011])

​

Common Use Cases

​

Debugging Issues

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

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

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

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

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

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

​

How the query is matched

• Every word must appear somewhere in the record, in any order and in any field. query="security deprecated" finds records that mention both.
• AND, OR, NOT, quotes, parentheses and field: prefixes are ordinary words. query="security NOT deprecated" requires “not” and “deprecated” too, and query='"database migration"' is not a phrase search: the two words can appear anywhere. To narrow results, use the obs_type, project, dateStart and dateEnd parameters.
• Case does not matter. Punctuation inside a word splits it into parts that must appear together, in order, so query="worker-service.ts" finds that file name, but not a record that only mentions “worker”, “service” and “ts” apart.
• Words can match inside longer words when nothing matches whole words. If no record contains every whole word, each word must still appear, but may be part of a longer one, so query="migrat" finds “migration”. Text in scripts written without spaces between words (Chinese, Japanese, Korean, Thai and others) is always matched this way.

query="database migration"       # records mentioning both words, anywhere
query="worker-service.ts"         # a file name
query="security NOT deprecated"  # all three words, "not" included: there are no operators

​

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

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

# 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

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

• 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:
   WORKER_PORT=$(jq -r .CLAUDE_MEM_WORKER_PORT ~/.claude-mem/settings.json)
   curl "http://127.0.0.1:$WORKER_PORT/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

• IDs from different project (use project parameter)
• IDs were deleted
• Typo in ID numbers

# Verify IDs exist
search(query="<related-search>")

# Use correct project filter
get_observations(ids=[123, 456], project="correct-project-name")

​

Token Limit Errors

# 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

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

​

Next Steps

• Progressive Disclosure - Philosophy behind 3-layer workflow
• Architecture Overview - System components
• Database Schema - Understanding the data structure
• Claude Desktop Setup - Installation and configuration