my-project-public

repository

loading code, commits, and activity

repositories

loading repo index

#1	---
#2	title: Criteria Retrieval
#3	---
#4
#5	Mem0's Criteria Retrieval feature allows you to retrieve memories based on your defined criteria. It goes beyond generic semantic relevance and ranks memories based on what matters to your application: emotional tone, intent, behavioral signals, or other custom traits.
#6
#7	Instead of just searching for "how similar a memory is to this query," you can define what relevance truly means for your project. For example:
#8
#9	- Prioritize joyful memories when building a wellness assistant
#10	- Downrank negative memories in a productivity-focused agent
#11	- Highlight curiosity in a tutoring agent
#12
#13	You define criteria: custom attributes like "joy", "negativity", "confidence", or "urgency", and assign weights to control how they influence scoring. When you search, Mem0 uses these to re-rank semantically relevant memories, favoring those that better match your intent.
#14
#15	This gives you nuanced, intent-aware memory search that adapts to your use case.
#16
#17
#18
#19	## When to Use Criteria Retrieval
#20
#21	Use Criteria Retrieval if:
#22
#23	- You’re building an agent that should react to emotions or behavioral signals
#24	- You want to guide memory selection based on context, not just content
#25	- You have domain-specific signals like "risk", "positivity", "confidence", etc. that shape recall
#26
#27
#28
#29	## Setting Up Criteria Retrieval
#30
#31	Let’s walk through how to configure and use Criteria Retrieval step by step.
#32
#33	### Initialize the Client
#34
#35	Before defining any criteria, make sure to initialize the `MemoryClient` with your credentials and project ID:
#36
#37	```python
#38	from mem0 import MemoryClient
#39
#40	client = MemoryClient(
#41	api_key="your_mem0_api_key",
#42	org_id="your_organization_id",
#43	project_id="your_project_id"
#44	)
#45	```
#46
#47	### Define Your Criteria
#48
#49	Each criterion includes:
#50	- A `name` (used in scoring)
#51	- A `description` (interpreted by the LLM)
#52	- A `weight` (how much it influences the final score)
#53
#54	```python
#55	retrieval_criteria = [
#56	{
#57	"name": "joy",
#58	"description": "Measure the intensity of positive emotions such as happiness, excitement, or amusement expressed in the sentence. A higher score reflects greater joy.",
#59	"weight": 3
#60	},
#61	{
#62	"name": "curiosity",
#63	"description": "Assess the extent to which the sentence reflects inquisitiveness, interest in exploring new information, or asking questions. A higher score reflects stronger curiosity.",
#64	"weight": 2
#65	},
#66	{
#67	"name": "emotion",
#68	"description": "Evaluate the presence and depth of sadness or negative emotional tone, including expressions of disappointment, frustration, or sorrow. A higher score reflects greater sadness.",
#69	"weight": 1
#70	}
#71	]
#72	```
#73
#74	### Apply Criteria to Your Project
#75
#76	Once defined, register the criteria to your project:
#77
#78	```python
#79	client.project.update(retrieval_criteria=retrieval_criteria)
#80	```
#81
#82	Criteria apply project-wide. Once set, they affect all searches automatically.
#83
#84
#85	## Example Walkthrough
#86
#87	After setting up your criteria, you can use them to filter and retrieve memories. Here's an example:
#88
#89	### Add Memories
#90
#91	```python
#92	messages = [
#93	{"role": "user", "content": "What a beautiful sunny day! I feel so refreshed and ready to take on anything!"},
#94	{"role": "user", "content": "I've always wondered how storms form—what triggers them in the atmosphere?"},
#95	{"role": "user", "content": "It's been raining for days, and it just makes everything feel heavier."},
#96	{"role": "user", "content": "Finally I get time to draw something today, after a long time!! I am super happy today."}
#97	]
#98
#99	client.add(messages, user_id="alice")
#100	```
#101
#102	### Run Standard vs. Criteria-Based Search
#103
#104	```python
#105	# Search with criteria enabled
#106	filters = {"user_id": "alice"}
#107	results_with_criteria = client.search(
#108	query="Why I am feeling happy today?",
#109	filters=filters
#110	)
#111
#112	# To disable criteria for a specific search
#113	results_without_criteria = client.search(
#114	query="Why I am feeling happy today?",
#115	filters=filters,
#116	use_criteria=False # Disable criteria-based scoring
#117	)
#118	```
#119
#120	### Compare Results
#121
#122	### Search Results (with Criteria)
#123	```python
#124	[
#125	{"memory": "User feels refreshed and ready to take on anything on a beautiful sunny day", "score": 0.666, ...},
#126	{"memory": "User finally has time to draw something after a long time", "score": 0.616, ...},
#127	{"memory": "User is happy today", "score": 0.500, ...},
#128	{"memory": "User is curious about how storms form and what triggers them in the atmosphere.", "score": 0.400, ...},
#129	{"memory": "It has been raining for days, making everything feel heavier.", "score": 0.116, ...}
#130	]
#131	```
#132
#133	### Search Results (without Criteria)
#134	```python
#135	[
#136	{"memory": "User is happy today", "score": 0.607, ...},
#137	{"memory": "User feels refreshed and ready to take on anything on a beautiful sunny day", "score": 0.512, ...},
#138	{"memory": "It has been raining for days, making everything feel heavier.", "score": 0.4617, ...},
#139	{"memory": "User is curious about how storms form and what triggers them in the atmosphere.", "score": 0.340, ...},
#140	{"memory": "User finally has time to draw something after a long time", "score": 0.336, ...},
#141	]
#142	```
#143
#144	## Search Results Comparison
#145
#146	1. Memory Ordering: With criteria, memories with high joy scores (like feeling refreshed and drawing) are ranked higher. Without criteria, the most relevant memory ("User is happy today") comes first.
#147	2. Score Distribution: With criteria, scores are more spread out (0.116 to 0.666) and reflect the criteria weights. Without criteria, scores are more clustered (0.336 to 0.607) and based purely on relevance.
#148	3. Trait Sensitivity: "Rainy day" content is penalized due to negative tone, while "Storm curiosity" is recognized and scored accordingly.
#149
#150
#151
#152	## Key Differences vs. Standard Search
#153
#154	\| Aspect \| Standard Search \| Criteria Retrieval \|
#155	\|-------------------------\|--------------------------------------\|-------------------------------------------------\|
#156	\| Ranking Logic \| Semantic similarity only \| Semantic + LLM-based criteria scoring \|
#157	\| Control Over Relevance \| None \| Fully customizable with weighted criteria \|
#158	\| Memory Reordering \| Static based on similarity \| Dynamically re-ranked by intent alignment \|
#159	\| Emotional Sensitivity \| No tone or trait awareness \| Incorporates emotion, tone, or custom behaviors \|
#160	\| Activation \| Default (no criteria defined) \| Enabled when criteria are defined in project \|
#161
#162	<Note>
#163	If no criteria are defined for a project, search behaves normally based on semantic similarity only.
#164	</Note>
#165
#166
#167
#168	## Best Practices
#169
#170	- Choose 3-5 criteria that reflect your application's intent
#171	- Make descriptions clear and distinct; these are interpreted by an LLM
#172	- Use stronger weights to amplify the impact of important traits
#173	- Avoid redundant or ambiguous criteria (e.g., "positivity" and "joy")
#174	- Always handle empty result sets in your application logic
#175
#176
#177
#178	## How It Works
#179
#180	1. Criteria Definition: Define custom criteria with a name, description, and weight. These describe what matters in a memory (e.g., joy, urgency, empathy).
#181	2. Project Configuration: Register these criteria using `project.update()`. They apply at the project level and automatically influence all searches.
#182	3. Memory Retrieval: When you perform a search, Mem0 first retrieves relevant memories based on the query.
#183	4. Weighted Scoring: Each retrieved memory is evaluated and scored against your defined criteria and weights.
#184
#185	This lets you prioritize memories that align with your agent's goals and not just those that look similar to the query.
#186
#187	<Note>
#188	Criteria retrieval is automatically enabled when criteria are defined in your project. Use `use_criteria=False` in search to temporarily disable it for a specific query.
#189	</Note>
#190
#191
#192
#193	## Summary
#194
#195	- Define what "relevant" means using criteria
#196	- Apply them per project via `project.update()`
#197	- Criteria-aware search activates automatically when criteria are configured
#198	- Build agents that reason not just with relevance, but contextual importance
#199
#200	---
#201
#202	Need help designing or tuning your criteria?
#203
#204	<Snippet file="get-help.mdx" />
#205

z6Mkq5mY3JWtxoxUobWcfNHm7AkRubgSWEZTkBVqZXJviFZ5/my-project-public