- Prioritize joyful memories when building a wellness assistant
- Downrank negative memories in a productivity-focused agent
- Highlight curiosity in a tutoring agent
search
, Mem0 uses these to re-rank memories that are semantically relevant, favoring those that better match your intent.
This gives you nuanced, intent-aware memory search that adapts to your use case.
When to Use Criteria Retrieval
Use Criteria Retrieval if:- You’re building an agent that should react to emotions or behavioral signals
- You want to guide memory selection based on context, not just content
- You have domain-specific signals like “risk”, “positivity”, “confidence”, etc. that shape recall
Setting Up Criteria Retrieval
Let’s walk through how to configure and use Criteria Retrieval step by step.Initialize the Client
Before defining any criteria, make sure to initialize theMemoryClient
with your credentials and project ID:
Define Your Criteria
Each criterion includes:- A
name
(used in scoring) - A
description
(interpreted by the LLM) - A
weight
(how much it influences the final score)
Apply Criteria to Your Project
Once defined, register the criteria to your project:version="v2"
.
Example Walkthrough
After setting up your criteria, you can use them to filter and retrieve memories. Here’s an example:Add Memories
Run Standard vs. Criteria-Based Search
Compare Results
Search Results (with Criteria)
Search Results (without Criteria)
Search Results Comparison
- Memory Ordering: With criteria, memories with high joy scores (like feeling refreshed and drawing) are ranked higher, while without criteria, the most relevant memory (“User is happy today”) comes first.
- Score Distribution: With criteria, scores are more spread out (0.116 to 0.666) and reflect the criteria weights, while without criteria, scores are more clustered (0.336 to 0.607) and based purely on relevance.
- Trait Sensitivity: “Rainy day” content is penalized due to negative tone. “Storm curiosity” is recognized and scored accordingly.
Key Differences vs. Standard Search
Aspect | Standard Search | Criteria Retrieval |
---|---|---|
Ranking Logic | Semantic similarity only | Semantic + LLM-based criteria scoring |
Control Over Relevance | None | Fully customizable with weighted criteria |
Memory Reordering | Static based on similarity | Dynamically re-ranked by intent alignment |
Emotional Sensitivity | No tone or trait awareness | Incorporates emotion, tone, or custom behaviors |
Version Required | Defaults | search(version="v2") |
If no criteria are defined for a project,
version="v2"
behaves like normal search.Best Practices
- Choose 3–5 criteria that reflect your application’s intent
- Make descriptions clear and distinct, those are interpreted by an LLM
- Use stronger weights to amplify impact of important traits
- Avoid redundant or ambiguous criteria (e.g. “positivity” + “joy”)
- Always handle empty result sets in your application logic
How It Works
- Criteria Definition: Define custom criteria with a name, description, and weight. These describe what matters in a memory (e.g., joy, urgency, empathy).
- Project Configuration: Register these criteria using
project.update()
. They apply at the project level and influence all searches usingversion="v2"
. - Memory Retrieval: When you perform a search with
version="v2"
, Mem0 first retrieves relevant memories based on the query and your defined criteria. - Weighted Scoring: Each retrieved memory is evaluated and scored against the defined criteria and weights.
Criteria retrieval is currently supported only in search v2. Make sure to use
version="v2"
when performing searches with custom criteria.Summary
- Define what “relevant” means using criteria
- Apply them per project via
project.update()
- Use
version="v2"
to activate criteria-aware search - Build agents that reason not just with relevance, but contextual importance
Need help designing or tuning your criteria?