diff --git a/docs/faqs.mdx b/docs/faqs.mdx
index 6748c8d2..ef0fa64a 100644
--- a/docs/faqs.mdx
+++ b/docs/faqs.mdx
@@ -107,9 +107,25 @@ iconType: "solid"
Note that the `/tmp` directory in Lambda has a size limit of 512MB and its contents are not persistent between function invocations.
+
+ Metadata is the recommended approach for incorporating additional information with Mem0. You can store any type of structured data as metadata during the `add` method, such as location, timestamp, weather conditions, user state, or application context. This enriches your memories with valuable contextual information that can be used for more precise retrieval and filtering.
+
+ During retrieval, you have two main approaches for using metadata:
+
+ 1. **Pre-filtering**: Include metadata parameters in your initial search query to narrow down the memory pool
+ 2. **Post-processing**: Retrieve a broader set of memories based on query, then apply metadata filters to refine the results
+
+ Examples of useful metadata you might store:
+
+ - **Contextual information**: Location, time, device type, application state
+ - **User attributes**: Preferences, skill levels, demographic information
+ - **Interaction details**: Conversation topics, sentiment, urgency levels
+ - **Custom tags**: Any domain-specific categorization relevant to your application
+
+ This flexibility allows you to create highly contextually aware AI applications that can adapt to specific user needs and situations. Metadata provides an additional dimension for memory retrieval, enabling more precise and relevant responses.
+
+
-
-
diff --git a/docs/features/advanced-retrieval.mdx b/docs/features/advanced-retrieval.mdx
index fe31357c..2d6efc7b 100644
--- a/docs/features/advanced-retrieval.mdx
+++ b/docs/features/advanced-retrieval.mdx
@@ -14,23 +14,77 @@ Mem0's **Advanced Retrieval** feature delivers superior search results by levera
client.search(query, keyword_search=True, user_id='alex')
```
+ **Example:**
+ ```python
+ # Search for memories about food preferences with keyword search enabled
+ query = "What are my food preferences?"
+ results = client.search(query, keyword_search=True, user_id='alex')
+
+ # Output might include:
+ # - "Vegetarian. Allergic to nuts." (highly relevant)
+ # - "Prefers spicy food and enjoys Thai cuisine" (relevant)
+ # - "Mentioned disliking sea food during restaurant discussion" (keyword match)
+
+ # Without keyword_search=True, only the most relevant memories would be returned:
+ # - "Vegetarian. Allergic to nuts." (highly relevant)
+ # - "Prefers spicy food and enjoys Thai cuisine" (relevant)
+ # The keyword-based match about "sea food" would be excluded
+ ```
+
2. **Reranking**
- Reranking allows you to reorder the memories returned by the default search based on relevance. This parameter is set to `false` by default. When enabled, it reorders the memories based on the relevance score.
+ Normal retrieval gives you memories sorted in order of their relevancy, but the order may not be perfect. Reranking uses a deep neural network to correct this order, ensuring the most relevant memories appear first. If you are concerned about the order of memories, or want that the best results always comes at top then use reranking. This parameter is set to `false` by default. When enabled, it reorders the memories based on a more accurate relevance score.
```python
client.search(query, rerank=True, user_id='alex')
```
+ **Example:**
+ ```python
+ # Search for travel plans with reranking enabled
+ query = "What are my travel plans?"
+ results = client.search(query, rerank=True, user_id='alex')
+
+ # Without reranking, results might be ordered like:
+ # 1. "Traveled to France last year" (less relevant to current plans)
+ # 2. "Planning a trip to Japan next month" (more relevant to current plans)
+ # 3. "Interested in visiting Tokyo restaurants" (relevant to current plans)
+
+ # With reranking enabled, results would be reordered:
+ # 1. "Planning a trip to Japan next month" (most relevant to current plans)
+ # 2. "Interested in visiting Tokyo restaurants" (highly relevant to current plans)
+ # 3. "Traveled to France last year" (less relevant to current plans)
+ ```
+
3. **Filtering**
- Filtering enables you to narrow down the search results by applying specific criteria. This parameter is set to `false` by default. Activating it enhances search precision, potentially reducing recall by a small margin.
+ Filtering allows you to narrow down search results by applying specific criterias. This parameter is set to `false` by default. When activated, it significantly enhances search precision by removing irrelevant memories, though it may slightly reduce recall. Filtering is particularly useful when you need highly specific information.
```python
client.search(query, filter_memories=True, user_id='alex')
```
-**Note:** You can enable or disable these search modes by passing the respective parameters to the `search` method. There is no required sequence for these modes, and any combination can be used based on your needs.
+ **Example:**
+ ```python
+ # Search for dietary restrictions with filtering enabled
+ query = "What are my dietary restrictions?"
+ results = client.search(query, filter_memories=True, user_id='alex')
+
+ # Without filtering, results might include:
+ # - "Vegetarian. Allergic to nuts." (directly relevant)
+ # - "I enjoy cooking Italian food on weekends" (somewhat related to food)
+ # - "Mentioned disliking seafood during restaurant discussion" (food-related)
+ # - "Prefers to eat dinner at 7pm" (tangentially food-related)
+
+ # With filtering enabled, results would be focused:
+ # - "Vegetarian. Allergic to nuts." (directly relevant)
+ # - "Mentioned disliking seafood during restaurant discussion" (relevant restriction)
+ #
+ # The filtering process removes memories that are about food preferences
+ # but not specifically about dietary restrictions
+ ```
+
+ You can enable or disable these search modes by passing the respective parameters to the `search` method. There is no required sequence for these modes, and any combination can be used based on your needs.
### Latency Numbers
diff --git a/docs/openapi.json b/docs/openapi.json
index 90c6ab2f..4443ffb3 100644
--- a/docs/openapi.json
+++ b/docs/openapi.json
@@ -4743,7 +4743,7 @@
"nullable": true
},
"metadata": {
- "description": "Additional metadata associated with the memory, which can be used to store any additional information or context about the memory.",
+ "description": "Additional metadata associated with the memory, which can be used to store any additional information or context about the memory. Best practice for incorporating additional information is through metadata (e.g. location, time, ids, etc.). During retrieval, you can either use these metadata alongside the query to fetch relevant memories or retrieve memories based on the query first and then refine the results using metadata during post-processing.",
"title": "Metadata",
"type": "object",
"properties": {
diff --git a/docs/platform/quickstart.mdx b/docs/platform/quickstart.mdx
index 659ad36f..81316c80 100644
--- a/docs/platform/quickstart.mdx
+++ b/docs/platform/quickstart.mdx
@@ -173,6 +173,8 @@ curl -X POST "https://api.mem0.ai/v1/memories/" \
Messages passed along with `user_id`, `run_id`, or `app_id` are stored as user memories, while messages from the assistant are excluded from memory. To store messages for the assistant, use `agent_id` exclusively and avoid including other IDs, such as user_id, alongside it. This ensures the memory is properly attributed to the assistant.
+Metadata allows you to store structured information (location, timestamp, user state) with memories. Add it during creation to enable precise filtering and retrieval during searches.
+
#### Short-term memory for a user session
@@ -489,6 +491,7 @@ curl -X POST "https://api.mem0.ai/v1/memories/search/" \
Use category and metadata filters:
+
```python Python