> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/Gentleman-Programming/engram/llms.txt
> Use this file to discover all available pages before exploring further.

# 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.

<Note>
  This is a **core tool** in the agent profile, always loaded in the MCP context.
</Note>

## Parameters

<ParamField path="query" type="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
</ParamField>

<ParamField path="type" 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:**

  ```json theme={null}
  {
    "query": "authentication",
    "type": "decision"
  }
  ```
</ParamField>

<ParamField path="project" type="string">
  Filter results by project name

  Only returns observations associated with the specified project.

  **Example:**

  ```json theme={null}
  {
    "query": "auth middleware",
    "project": "my-api"
  }
  ```
</ParamField>

<ParamField path="scope" type="string">
  Filter observations by visibility scope

  **Options:**

  * `project` (default) — project-scoped observations
  * `personal` — cross-project personal knowledge

  **Example:**

  ```json theme={null}
  {
    "query": "error handling pattern",
    "scope": "personal"
  }
  ```
</ParamField>

<ParamField path="limit" type="number">
  Maximum number of results to return

  **Default:** `10`

  **Maximum:** `20`

  Results are ranked by FTS5 BM25 relevance score.
</ParamField>

## Response

<ResponseField name="results" type="array">
  Array of search results, ranked by relevance
</ResponseField>

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

```json theme={null}
{
  "query": "authentication"
}
```

Returns all observations containing "authentication" across all projects and types.

### Search by Type

```json theme={null}
{
  "query": "N+1 query",
  "type": "bugfix"
}
```

Returns only bugfix observations about N+1 queries.

### Project-Specific Search

```json theme={null}
{
  "query": "middleware",
  "project": "my-api"
}
```

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

### Personal Knowledge

```json theme={null}
{
  "query": "error handling",
  "scope": "personal",
  "limit": 5
}
```

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

### Multi-Word Query

```json theme={null}
{
  "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):

```json theme={null}
{
  "query": "JWT AND authentication NOT session"
}
```

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

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

## 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:

<Steps>
  <Step title="Search first">
    ```json theme={null}
    {
      "query": "authentication middleware"
    }
    ```

    Returns compact results with observation IDs.
  </Step>

  <Step title="Get full content (if needed)">
    ```json theme={null}
    {
      "id": 42
    }
    ```

    Use [`mem_get_observation`](/mcp/mem-get-observation) to retrieve untruncated content.
  </Step>

  <Step title="View timeline (optional)">
    ```json theme={null}
    {
      "observation_id": 42,
      "before": 5,
      "after": 5
    }
    ```

    Use [`mem_timeline`](/mcp/mem-timeline) to see chronological context.
  </Step>
</Steps>

## 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`](/mcp/mem-get-observation) - Get full content by ID
* [`mem_timeline`](/mcp/mem-timeline) - View chronological context around a result
* [`mem_context`](/mcp/mem-context) - Get recent memory context (not search-based)
* [`mem_save`](/mcp/mem-save) - Save new observations