Skip to main content

​
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 keywordsExamples:
  • "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 typeRecognized 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 nameOnly returns observations associated with the specified project.Example:
{
  "query": "auth middleware",
  "project": "my-api"
}
​
scope
string
Filter observations by visibility scopeOptions:
  • project (default) — project-scoped observations
  • personal — cross-project personal knowledge
Example:
{
  "query": "error handling pattern",
  "scope": "personal"
}
​
limit
number
Maximum number of results to returnDefault: 10Maximum: 20Results 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

{
  "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. 
{
  "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

Build docs developers (and LLMs) love

Get started for freeTalk to us