mem_search

Search persistent memory across all sessions

Overview

Search your persistent memory using natural language or keywords. Powered by SQLite FTS5 full-text search with BM25 ranking, this tool finds past decisions, bugs fixed, patterns used, files changed, and any context from previous coding sessions.

This is a core tool in the agent profile, always loaded in the MCP context.

Parameters

query · string · required

Search query — natural language or keywords

Examples:

• "JWT authentication"
• "N+1 query fix"
• "FTS5 sanitization"
• "authentication middleware decision"

The query is automatically sanitized for FTS5:

• Each term is wrapped in quotes to handle special characters
• Boolean operators are preserved (AND, OR, NOT)
• Safe to include user input directly

type · string

Filter results by observation type

Recognized types:

• tool_use — automatic captures from agent tool calls
• file_change — file modifications
• command — shell commands executed
• file_read — files read during sessions
• search — search operations performed
• manual — manually saved observations
• decision — architectural or technical decisions
• architecture — system design, patterns
• bugfix — bug fixes
• pattern — conventions, guidelines

Example:

{
  "query": "authentication",
  "type": "decision"
}

project · string

Filter results by project name

Only returns observations associated with the specified project.

Example:

{
  "query": "auth middleware",
  "project": "my-api"
}

scope · string

Filter observations by visibility scope

Options:

• project (default) — project-scoped observations
• personal — cross-project personal knowledge

Example:

{
  "query": "error handling pattern",
  "scope": "personal"
}

limit · number

Maximum number of results to return

Default: 10

Maximum: 20

Results are ranked by FTS5 BM25 relevance score.

Response

results · array

Array of search results, ranked by relevance

Each result includes:

• ID — observation identifier for mem_get_observation or mem_timeline
• Type — observation category
• Title — short summary
• Content — truncated preview (up to 300 characters)
• Project — associated project (if any)
• Scope — project or personal
• Created timestamp — when it was saved

Example response:

Found 3 memories:

[1] #42 (bugfix) — Fixed FTS5 syntax error on special chars
    **What**: Wrapped each search term in quotes before passing to FTS5 MATCH
    **Why**: Users typing queries like 'fix auth bug' would crash because FTS5 interprets special chars as operators
    **Where**: internal/store/store.go — sanitizeFTS() function...
    2026-03-01T14:23:45Z | project: engram | scope: project

[2] #87 (decision) — Switched from sessions to JWT
    **What**: Replaced express-session with jsonwebtoken for auth
    **Why**: Session storage doesn't scale across multiple instances
    **Where**: src/middleware/auth.ts, src/routes/login.ts...
    2026-02-28T10:15:30Z | project: my-api | scope: project

[3] #12 (pattern) — Go error handling pattern
    **What**: Established consistent error wrapping with fmt.Errorf and %w
    **Why**: Makes error traces debuggable without stack traces
    **Where**: All internal/* packages...
    2026-02-15T08:45:12Z | scope: personal

If no results are found:

No memories found for: "your query"

Usage Examples

Basic Search

{
  "query": "authentication"
}

Returns all observations containing “authentication” across all projects and types.

Search by Type

{
  "query": "N+1 query",
  "type": "bugfix"
}

Returns only bugfix observations about N+1 queries.

Project-Specific Search

{
  "query": "middleware",
  "project": "my-api"
}

Returns observations about “middleware” only from the “my-api” project.

Personal Knowledge

{
  "query": "error handling",
  "scope": "personal",
  "limit": 5
}

Returns up to 5 cross-project observations about error handling.

Multi-Word Query

{
  "query": "JWT authentication decision"
}

FTS5 tokenizes the query and ranks results by how many terms match and their relevance.

FTS5 Search Behavior

Tokenization

FTS5 tokenizes both the query and stored content:

• Case-insensitive — “JWT” matches “jwt” and “Jwt”
• Stem matching — “running” matches “run”, “runs”, “ran”
• Special characters — automatically quoted to prevent syntax errors

Ranking (BM25)

Results are ranked by BM25 relevance:

1. Term frequency — how often the query terms appear
2. Document length — shorter documents rank higher for the same term frequency
3. Inverse document frequency — rare terms boost ranking more than common terms

Boolean Operators

FTS5 supports boolean search (advanced):

{
  "query": "JWT AND authentication NOT session"
}

This finds observations with “JWT” and “authentication” but excludes those containing “session”.

For most use cases, simple natural language queries work best. FTS5 handles the ranking automatically.

When to Use

• Context recovery — recall what was done in previous sessions
• Decision lookup — find why an architectural choice was made
• Bug reference — remember how a similar bug was fixed
• Pattern discovery — find established conventions
• File changes — locate where specific changes were made

Progressive Disclosure Pattern

mem_search returns truncated content to save tokens. For full details:

1. Search first

   {
     "query": "authentication middleware"
   }
   

   Returns compact results with observation IDs.

2. Get full content (if needed)

   {
     "id": 42
   }
   

   Use mem_get_observation to retrieve untruncated content.

3. View timeline (optional)

   {
     "observation_id": 42,
     "before": 5,
     "after": 5
   }
   

   Use mem_timeline to see chronological context.

Search Performance

• FTS5 index — full-text search index on title and content columns
• Sub-millisecond queries — typical search completes in less than 5ms
• No external dependencies — pure SQLite, no vector database

Empty Results

If mem_search returns no results:

1. Broaden the query — try fewer or more general terms
2. Check the project filter — remove project filter to search all projects
3. Check the type filter — remove type filter to search all categories
4. Verify scope — try scope: "personal" if searching for cross-project knowledge

Related Tools

• mem_get_observation - Get full content by ID
• mem_timeline - View chronological context around a result
• mem_context - Get recent memory context (not search-based)
• mem_save - Save new observations