# How Mem0 Searches Memory

Mem0’s search operation lets agents ask natural-language questions and get back the memories that matter most. Like a smart librarian, it finds exactly what you need from everything you’ve stored.

## Key terms

- **Query**: Natural-language question or statement you pass to `search`.
- **Filters**: JSON logic (AND/OR, comparison operators) that narrows results by user, categories, dates, etc.
- **top_k / threshold**: Controls how many memories return and the minimum similarity score.
- **Rerank**: Optional second pass that boosts precision when a reranker is configured.

## Architecture

1. **Query processing**  
   Mem0 cleans and enriches your natural-language query so the downstream embedding search is accurate.  
2. **Vector search**  
   Embeddings locate the closest memories using cosine similarity across your scoped dataset.  
3. **Filtering & reranking**  
   Logical filters narrow candidates; rerankers or thresholds fine-tune ordering.  
4. **Results delivery**  
   Formatted memories (with metadata and timestamps) return to your agent or calling service.

## How does it work?

Search converts your natural language question into a vector embedding, then finds memories with similar embeddings in your database. The results are ranked by similarity score and can be further refined with filters or reranking.

```python
# Minimal example that shows the concept in action
# Platform API
client.search("What are Alice's hobbies?", filters={"user_id": "alice"})

# OSS
m.search("What are Alice's hobbies?", filters={"user_id": "alice"})
```  
Always provide at least a `user_id` filter to scope searches to the right user’s memories. This prevents cross-contamination between users.

## When should you use it?
- **Context retrieval** - When your agent needs past context to generate better responses
- **Personalization** - To recall user preferences, history, or past interactions
- **Fact checking** - To verify information against stored memories before responding
- **Decision support** - When agents need relevant background information to make decisions

## Platform vs OSS usage

| Capability                                     | Mem0 Platform                                                     | Mem0 OSS                                                        |
|-----------------------------------------------|------------------------------------------------------------------|------------------------------------------------------------------|
| **Entity IDs on search / get_all**           | Inside `filters={"user_id": "alice"}`                        | Inside `filters={"user_id": "alice"}`                      |
| **Filter syntax**                             | Logical operators (`AND`, `OR`, comparisons) with field-level access | Basic field filters, extend via Python hooks                    |
| **Reranking**                                 | Toggle `rerank=True` with managed reranker catalog               | Requires configuring local or third-party rerankers             |
| **Thresholds**                                | Request-level configuration (`threshold`, `top_k`)              | Controlled via SDK parameters                                   |
| **Response metadata**                          | Includes confidence scores, timestamps, dashboard visibility     | Determined by your storage backend                               |

## Search with Mem0 Platform

### Python
```python
from mem0 import MemoryClient

client = MemoryClient(api_key="your-api-key")

query = "What do you know about me?"
filters = {"OR": [{"user_id": "alice"},{"agent_id": {"in": ["travel-assistant", "customer-support"]}}]}

results = client.search(query, filters=filters)
```

### JavaScript
```javascript
import { MemoryClient } from "mem0ai";

const client = new MemoryClient({apiKey: "your-api-key"});

const query = "I'm craving some pizza. Any recommendations?";
const filters = {AND: [{ user_id: "alice" }]};

const results = await client.search(query, { filters });
```

## Search with Mem0 Open Source

### Python
```python
from mem0 import Memory

m = Memory()

# Simple search: entity IDs go in `filters`
related_memories = m.search("Should I drink coffee or tea?", filters={"user_id": "alice"})

# Search with additional metadata filters (combine entity + metadata in the same dict)
memories = m.search(
    "food preferences",
    filters={"user_id": "alice", "categories": {"contains": "diet"}},
)
```

### JavaScript
```javascript
import { Memory } from 'mem0ai/oss';

const memory = new Memory();

// Simple search: entity IDs go inside `filters`
const relatedMemories = memory.search("Should I drink coffee or tea?", {
    filters: { userId: "alice" },
});

// Combine entity + metadata filters in the same filters object
const memories = memory.search("food preferences", {
    filters: { userId: "alice", categories: { contains: "diet" } },
});
```

Expect an array of memory documents. Platform responses include vectors, metadata, and timestamps; OSS returns your stored schema.

### Explain OSS search scores

OSS search combines semantic similarity with optional keyword and entity signals. Pass `explain=True` when tuning retrieval quality or debugging why a memory ranked where it did:

### Python
```python
results = m.search(
    "food preferences",
    filters={"user_id": "alice"},
    explain=True,
)

print(results["results"][0]["score_details"])
```

### JavaScript
```javascript
const results = await memory.search("food preferences", {
    filters: { user_id: "alice" },
    explain: true,
});
console.log(results.results[0].score_details);
```

Each result includes `score_details` with the semantic score, normalized BM25 score, entity boost, raw combined score, maximum possible score, final score, and threshold used for filtering. The field is omitted unless `explain` is enabled, so existing response shapes stay unchanged.

## Filter patterns

Filters help narrow down search results. Common use cases:

**Filter by Session Context:**

```python
# Get memories from a specific agent session
client.search("query", filters={
    "AND": [{"user_id": "alice"},{"agent_id": "chatbot"},{"run_id": "session-123"}]
})
```

**Filter by Date Range:**

```python
# Platform only - date filtering
client.search("recent memories", filters={
    "AND": [{"user_id": "alice"},{"created_at": {"gte": "2024-07-01"}}]
})
```

**Filter by Categories:**

```python
# Platform only - category filtering
client.search("preferences", filters={
    "AND": [{"user_id": "alice"},{"categories": {"contains": "food"}}]
})
```

## Tips for better search

- **Use natural language**: Mem0 understands intent, so describe what you’re looking for naturally
- **Scope with user ID**: Always provide `user_id` to scope search to relevant memories
- **Combine filters**: Use AND/OR logic to create precise queries (Platform)
- **Consider wildcard filters**: Use wildcard filters (e.g., `run_id: "*"`) for broader matches
- **Tune parameters**: Adjust `top_k` for result count, `threshold` for relevance cutoff
- **Enable reranking**: Use `rerank=True` (default is `False`) when you have a reranker configured

**MCP Alternative**: With Mem0 MCP, AI agents can search their own memories proactively when needed.

### More Details

For the full list of filter logic, comparison operators, and optional search parameters, see the [Search Memory API Reference](https://docs.mem0.ai/api-reference/memory/search-memories).

## Put it into practice
- Revisit the [Add Memory](https://docs.mem0.ai/core-concepts/memory-operations/add) guide to ensure you capture the context you expect to retrieve.
- Configure rerankers and filters in [Advanced Retrieval](https://docs.mem0.ai/platform/features/advanced-retrieval) for higher precision.

## See it live
- [Support Inbox with Mem0](https://docs.mem0.ai/cookbooks/operations/support-inbox) demonstrates scoped search with rerankers.
- [Tavily Search with Mem0](https://docs.mem0.ai/cookbooks/integrations/tavily-search) shows hybrid search in action.