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.

# 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

Search with Mem0 Platform

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

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

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

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

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

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

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:

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

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

Filter by Categories:

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

Put it into practice

• Revisit the Add Memory guide to ensure you capture the context you expect to retrieve.
• Configure rerankers and filters in Advanced Retrieval for higher precision.

See it live

• Support Inbox with Mem0 demonstrates scoped search with rerankers.
• Tavily Search with Mem0 shows hybrid search in action.