---
title: "Searching Memories"
description: "Searching memories allows you to query, rank, and retrieve relevant stored facts and context using natural language queries, keyword matching, and semantic filters. The search engine combines seman..."
last_updated: "2026-10-11T17:38:36.46961+00:00"
canonical_url: "https://www.doc0.dev/docs/faa36707-7c28-4f69-a18f-700ff61c704e/guide/core-features/searching-memories"
---

## Overview

### Introduction

Searching memories allows you to query, rank, and retrieve relevant stored facts and context using natural language queries, keyword matching, and semantic filters. The search engine combines semantic vector similarity with keyword ranking (BM25) and entity boosting to surface the most contextually relevant information for users or AI agents.

> [!NOTE]
> Effective searches require at least one entity identifier (`user_id`, `agent_id`, or `run_id`) to scope the results and ensure data isolation.

---

### Running a Basic Search

You can search your memory store using the command-line interface or programmatically. 

To search memories using natural language via the command line:

1. Open your terminal.
2. Run the search command with your query and a user identifier:
   ```bash
   mem0 search "preferences" --user-id alice
   ```
3. (Optional) Customize the number of results returned using the `--top-k` flag and control the match strictness using `--threshold`:
   ```bash
   mem0 search "tools" --user-id alice --top-k 5 --threshold 0.2
   ```

---

### Refining Search Results

### Filtering and Scoping Options

When querying memories, you can restrict results using entity filters or custom JSON filter criteria.

| Option / Flag | Description |
| :--- | :--- |
| `--user-id` | Scopes the search to a specific user. |
| `--agent-id` | Scopes the search to a specific AI agent. |
| `--run-id` | Scopes the search to a specific execution run. |
| `--top-k` | Maximum number of results to return (default varies by client, typically 10 to 20). |
| `--threshold` | Minimum similarity score threshold between 0.0 and 1.0. |
| `--rerank` | Opt-in flag to invoke a secondary reranking model for higher precision. |
| `--keyword` | Enables hybrid keyword search alongside semantic search. |
| `--filter` | Applies structured metadata filters using JSON format. |

> [!TIP]
> You can combine semantic search with structured filters to query specific categories or metadata tags. For example:
> ```bash
> mem0 search "invoices" --user-id alice --filter '{"AND": [{"categories": {"in": ["work"]}}]}'
> ```

---

### Search Workflow

The following diagram illustrates how search queries are processed, scored, and returned to the user or agent:

```mermaid
flowchart TD
    A[User enters natural language query] --> B[Sanitize and extract query entities]
    B --> C[Run Semantic & Keyword Search]
    C --> D[Apply Filters & Entity Boosts]
    D --> E[Score and Rank Candidates]
    E --> F[Optional Reranking]
    F --> G[Return Formatted Results]
```

> [!WARNING]
> If a search query is submitted without an accompanying entity identifier (`user_id`, `agent_id`, or `run_id`), the system will reject the request with an error to maintain proper data scoping.

## Related

- [Managing Memories](https://www.doc0.dev/docs/faa36707-7c28-4f69-a18f-700ff61c704e/guide/core-features/managing-memories)
- [Organizing User Memories](https://www.doc0.dev/docs/faa36707-7c28-4f69-a18f-700ff61c704e/guide/how-to-guides/organizing-user-memories)


## Sitemap

See the full [sitemap](https://www.doc0.dev/docs/faa36707-7c28-4f69-a18f-700ff61c704e/llms.txt) for all pages in this wiki.