diff --git a/docs/api-reference/organizations-projects.mdx b/docs/api-reference/organizations-projects.mdx index 36a2ee9eb..e67d4d20c 100644 --- a/docs/api-reference/organizations-projects.mdx +++ b/docs/api-reference/organizations-projects.mdx @@ -79,7 +79,7 @@ new_project = client.project.create( ### Update Project Settings -Modify project configuration including custom instructions, categories, language preferences, retrieval criteria, and memory decay: +Modify project configuration including custom instructions, categories, language preferences, and memory decay: ```python # Update project with custom categories @@ -98,14 +98,6 @@ client.project.update( # Use the input language for memory storage and retrieval client.project.update(multilingual=True) -# Set retrieval criteria to control which memories are surfaced in search -client.project.update( - retrieval_criteria=[ - {"name": "relevance", "description": "How directly relevant this memory is to the current topic or user query", "weight": 3}, - {"name": "access_frequency", "description": "How often this memory has been accessed or surfaced recently", "weight": 1} - ] -) - # Enable Memory Decay (boosts recently-accessed memories at search time) client.project.update(decay=True) @@ -120,34 +112,6 @@ client.project.update( ) ``` -#### Set Retrieval Criteria - -`retrieval_criteria` is a per-project list of dictionaries (`List[Dict]`) that shapes how memories are ranked and filtered during search. Each dictionary has three fields: `name` (identifier), `description` (interpreted by the LLM to score each memory), and `weight` (relative influence on the final score). Use this to focus retrieval on intent-aligned or signal-specific memories: - -```python -client.project.update( - retrieval_criteria=[ - { - "name": "joy", - "description": "Measure the intensity of positive emotions such as happiness, excitement, or amusement expressed in the memory. A higher score reflects greater joy.", - "weight": 3 - }, - { - "name": "curiosity", - "description": "Assess the extent to which the memory reflects inquisitiveness or interest in exploring new information. A higher score reflects stronger curiosity.", - "weight": 2 - }, - { - "name": "access_frequency", - "description": "How often this memory has been accessed or surfaced recently.", - "weight": 1 - } - ] -) -``` - -Pass an empty list to clear all criteria and restore default retrieval behaviour. - #### Toggle Memory Decay `decay` is a per-project boolean that turns on [Memory Decay](/platform/features/memory-decay): a search-time ranking bias that reinforces recently-accessed memories and gently dampens stale ones. The flag is `false` by default; set it via the same project-update endpoint: diff --git a/docs/docs.json b/docs/docs.json index 8b64c9ed3..786d145f1 100644 --- a/docs/docs.json +++ b/docs/docs.json @@ -84,7 +84,6 @@ "pages": [ "platform/features/advanced-retrieval", "platform/advanced-memory-operations", - "platform/features/criteria-retrieval", "platform/features/custom-instructions", "platform/features/memory-decay" ] @@ -1231,6 +1230,10 @@ { "source": "/open-source/multimodal-support", "destination": "/open-source/features/multimodal-support" + }, + { + "source": "/platform/features/criteria-retrieval", + "destination": "/platform/features/advanced-retrieval" } ] } diff --git a/docs/llms.txt b/docs/llms.txt index 755cae4d7..9b4f15e65 100644 --- a/docs/llms.txt +++ b/docs/llms.txt @@ -204,7 +204,6 @@ If the user is on a pre-current major (Python < 2, TS < 3, or Platform `output_f ### Features - Advanced Retrieval - [Advanced Retrieval](https://docs.mem0.ai/platform/features/advanced-retrieval) [Platform]: Use when the user needs keyword search, reranking, or hybrid retrieval. -- [Criteria-Based Retrieval](https://docs.mem0.ai/platform/features/criteria-retrieval) [Platform]: Use when targeting memories by custom criteria, not just semantic similarity. - [Temporal Reasoning](https://docs.mem0.ai/platform/features/temporal-reasoning) [Platform]: Use when time-aware searches like last week, upcoming, or right now need better result ordering. - [Custom Instructions](https://docs.mem0.ai/platform/features/custom-instructions) [Platform]: Use when tailoring what Mem0 extracts and stores on Platform. - [Memory Decay](https://docs.mem0.ai/platform/features/memory-decay) [Platform]: Use when search results should boost recently-reinforced memories and dampen stale ones. Opt in per project; applies at search time and never filters candidates out. diff --git a/docs/platform/features/criteria-retrieval.mdx b/docs/platform/features/criteria-retrieval.mdx deleted file mode 100644 index db161b3ac..000000000 --- a/docs/platform/features/criteria-retrieval.mdx +++ /dev/null @@ -1,201 +0,0 @@ ---- -title: Criteria Retrieval -description: "Rank and retrieve memories based on custom-defined criteria like emotional tone, intent, and behavioral signals." ---- - -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. - -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: - -- Prioritize joyful memories when building a wellness assistant -- Downrank negative memories in a productivity-focused agent -- Highlight curiosity in a tutoring agent - -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. - -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 the `MemoryClient` with your credentials and project ID: - -```python -from mem0 import MemoryClient - -client = MemoryClient(api_key="your_mem0_api_key") -``` - -### 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) - -```python -retrieval_criteria = [ - { - "name": "joy", - "description": "Measure the intensity of positive emotions such as happiness, excitement, or amusement expressed in the sentence. A higher score reflects greater joy.", - "weight": 3 - }, - { - "name": "curiosity", - "description": "Assess the extent to which the sentence reflects inquisitiveness, interest in exploring new information, or asking questions. A higher score reflects stronger curiosity.", - "weight": 2 - }, - { - "name": "emotion", - "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.", - "weight": 1 - } -] -``` - -### Apply Criteria to Your Project - -Once defined, register the criteria to your project: - -```python -client.project.update(retrieval_criteria=retrieval_criteria) -``` - -Criteria apply project-wide. Once set, they affect all searches automatically. - - -## Example Walkthrough - -After setting up your criteria, you can use them to filter and retrieve memories. Here's an example: - -### Add Memories - -```python -messages = [ - {"role": "user", "content": "What a beautiful sunny day! I feel so refreshed and ready to take on anything!"}, - {"role": "user", "content": "I've always wondered how storms form, what triggers them in the atmosphere?"}, - {"role": "user", "content": "It's been raining for days, and it just makes everything feel heavier."}, - {"role": "user", "content": "Finally I get time to draw something today, after a long time!! I am super happy today."} -] - -client.add(messages, user_id="alice") -``` - -### Run Standard vs. Criteria-Based Search - -```python -# Search with criteria enabled -filters = {"user_id": "alice"} -results_with_criteria = client.search( - query="Why I am feeling happy today?", - filters=filters -) - -# To disable criteria for a specific search -results_without_criteria = client.search( - query="Why I am feeling happy today?", - filters=filters, - use_criteria=False # Disable criteria-based scoring -) -``` - -### Compare Results - -### Search Results (with Criteria) -```text -[ - {"memory": "User feels refreshed and ready to take on anything on a beautiful sunny day", "score": 0.666, ...}, - {"memory": "User finally has time to draw something after a long time", "score": 0.616, ...}, - {"memory": "User is happy today", "score": 0.500, ...}, - {"memory": "User is curious about how storms form and what triggers them in the atmosphere.", "score": 0.400, ...}, - {"memory": "It has been raining for days, making everything feel heavier.", "score": 0.116, ...} -] -``` - -### Search Results (without Criteria) -```text -[ - {"memory": "User is happy today", "score": 0.607, ...}, - {"memory": "User feels refreshed and ready to take on anything on a beautiful sunny day", "score": 0.512, ...}, - {"memory": "It has been raining for days, making everything feel heavier.", "score": 0.4617, ...}, - {"memory": "User is curious about how storms form and what triggers them in the atmosphere.", "score": 0.340, ...}, - {"memory": "User finally has time to draw something after a long time", "score": 0.336, ...}, -] -``` - -## Search Results Comparison - -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. -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. -3. **Trait Sensitivity**: "Rainy day" content is penalized due to negative tone, while "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 | -| Activation | Default (no criteria defined) | Enabled when criteria are defined in project | - - -If no criteria are defined for a project, search behaves normally based on semantic similarity only. - - - - -## Best Practices - -- Choose 3-5 criteria that reflect your application's intent -- Make descriptions clear and distinct; these are interpreted by an LLM -- Use stronger weights to amplify the impact of important traits -- Avoid redundant or ambiguous criteria (e.g., "positivity" and "joy") -- Always handle empty result sets in your application logic - - - -## How It Works - -1. **Criteria Definition**: Define custom criteria with a name, description, and weight. These describe what matters in a memory (e.g., joy, urgency, empathy). -2. **Project Configuration**: Register these criteria using `project.update()`. They apply at the project level and automatically influence all searches. -3. **Memory Retrieval**: When you perform a search, Mem0 first retrieves relevant memories based on the query. -4. **Weighted Scoring**: Each retrieved memory is evaluated and scored against your defined criteria and weights. - -This lets you prioritize memories that align with your agent's goals and not just those that look similar to the query. - - -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. `use_criteria` is a server-side parameter passed through to the Platform API: it is not a typed option in the SDK's `SearchMemoryOptions` interface, but the server accepts and processes it when included in the request body. - - - - -## Summary - -- Define what "relevant" means using criteria -- Apply them per project via `project.update()` -- Criteria-aware search activates automatically when criteria are configured -- Build agents that reason not just with relevance, but **contextual importance** - ---- - -Need help designing or tuning your criteria? - - diff --git a/docs/platform/platform-vs-oss.mdx b/docs/platform/platform-vs-oss.mdx index d24c38c1c..609497c6a 100644 --- a/docs/platform/platform-vs-oss.mdx +++ b/docs/platform/platform-vs-oss.mdx @@ -60,7 +60,6 @@ Mem0 offers two powerful ways to add memory to your AI applications. Choose base | **Multimodal support** | ✅ | ✅ | | **Custom categories** | ✅ | Limited | | **Advanced retrieval** | ✅ | ✅ | - | **Criteria retrieval** | ✅ | ❌ | | **Temporal reasoning** | ✅ (v3) | ❌ | | **Memory decay** | ✅ (v3) | ❌ | | **Graph memory** | ✅ Built-in | ✅ External graph store | diff --git a/integrations/mem0-plugin/skills/mem0/references/features.md b/integrations/mem0-plugin/skills/mem0/references/features.md index 1328f1fc7..1cfaba61f 100644 --- a/integrations/mem0-plugin/skills/mem0/references/features.md +++ b/integrations/mem0-plugin/skills/mem0/references/features.md @@ -8,7 +8,6 @@ Additional platform capabilities beyond core CRUD operations. - [Entity Linking](#entity-linking) - [Custom Categories](#custom-categories) - [Custom Instructions](#custom-instructions) -- [Criteria Retrieval](#criteria-retrieval) - [Feedback Mechanism](#feedback-mechanism) - [Memory Export](#memory-export) - [Group Chat](#group-chat) @@ -165,44 +164,6 @@ await client.updateProject({ customInstructions: "Your guidelines here..." }); --- -## Criteria Retrieval - -Custom attribute-based memory ranking using LLM-evaluated criteria with weights. Goes beyond semantic similarity to prioritize memories based on domain-specific signals. - -### Configuration - -```python -# Define criteria at project level -retrieval_criteria = [ - {"name": "joy", "description": "Positive emotions like happiness and excitement", "weight": 3}, - {"name": "curiosity", "description": "Inquisitiveness and desire to learn", "weight": 2}, - {"name": "urgency", "description": "Time-sensitive or high-priority items", "weight": 4}, -] -client.project.update(retrieval_criteria=retrieval_criteria) -``` - -```typescript -await client.updateProject({ - retrievalCriteria: [ - { name: 'joy', description: 'Positive emotions', weight: 3 }, - { name: 'urgency', description: 'Time-sensitive items', weight: 4 }, - ], -}); -``` - -### Usage - -Once configured, `client.search()` automatically applies criteria ranking: - -```python -# Criteria-weighted results returned automatically -results = client.search("Why am I feeling happy?", filters={"user_id": "alice"}) -``` - -**Best for:** Wellness assistants, tutoring platforms, productivity tools — any app needing intent-aware retrieval. - ---- - ## Feedback Mechanism Provide feedback on extracted memories to improve system quality over time. diff --git a/skills/mem0/references/features.md b/skills/mem0/references/features.md index 90e3308c9..f930d9a74 100644 --- a/skills/mem0/references/features.md +++ b/skills/mem0/references/features.md @@ -8,7 +8,6 @@ Additional platform capabilities beyond core CRUD operations. - [Entity Linking](#entity-linking) - [Custom Categories](#custom-categories) - [Custom Instructions](#custom-instructions) -- [Criteria Retrieval](#criteria-retrieval) - [Feedback Mechanism](#feedback-mechanism) - [Memory Export](#memory-export) - [Group Chat](#group-chat) @@ -165,44 +164,6 @@ await client.updateProject({ customInstructions: "Your guidelines here..." }); --- -## Criteria Retrieval - -Custom attribute-based memory ranking using LLM-evaluated criteria with weights. Goes beyond semantic similarity to prioritize memories based on domain-specific signals. - -### Configuration - -```python -# Define criteria at project level -retrieval_criteria = [ - {"name": "joy", "description": "Positive emotions like happiness and excitement", "weight": 3}, - {"name": "curiosity", "description": "Inquisitiveness and desire to learn", "weight": 2}, - {"name": "urgency", "description": "Time-sensitive or high-priority items", "weight": 4}, -] -client.project.update(retrieval_criteria=retrieval_criteria) -``` - -```typescript -await client.updateProject({ - retrievalCriteria: [ - { name: 'joy', description: 'Positive emotions', weight: 3 }, - { name: 'urgency', description: 'Time-sensitive items', weight: 4 }, - ], -}); -``` - -### Usage - -Once configured, `client.search()` automatically applies criteria ranking: - -```python -# Criteria-weighted results returned automatically -results = client.search("Why am I feeling happy?", filters={"user_id": "alice"}) -``` - -**Best for:** Wellness assistants, tutoring platforms, productivity tools — any app needing intent-aware retrieval. - ---- - ## Feedback Mechanism Provide feedback on extracted memories to improve system quality over time.