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:
- Open your terminal.
- Run the search command with your query and a user identifier:
mem0 search "preferences" --user-id alice - (Optional) Customize the number of results returned using the
--top-kflag and control the match strictness using--threshold: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:
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:
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.