From 696455fd62e4059dad3e260c704fe6198b8027ed Mon Sep 17 00:00:00 2001
From: Kartik <kartik.labhshetwar@mem0.ai>
Date: Fri, 14 Aug 2026 16:55:44 +0530
Subject: [PATCH] docs: contrast the advanced retrieval modes with distinct
 examples (#6904)

---
 docs/platform/features/advanced-retrieval.mdx | 22 +++++++++++++++----
 1 file changed, 18 insertions(+), 4 deletions(-)

diff --git a/docs/platform/features/advanced-retrieval.mdx b/docs/platform/features/advanced-retrieval.mdx
index c1b09cf0d..1a1a89ba0 100644
--- a/docs/platform/features/advanced-retrieval.mdx
+++ b/docs/platform/features/advanced-retrieval.mdx
@@ -99,16 +99,23 @@ results = client.search(
 
 ### Recommended Configurations
 
+`rerank` is the only lever here that changes result *order*. `filters`, `top_k`, and `threshold` change *which* memories come back, not how they're ordered. The two functions below send the same query and filters; the only difference is the `rerank` flag.
+
 <CodeGroup>
 ```python Python
-# Basic search - good for exploration
+# Fast path - use for exploratory search, or anywhere the user scans a list
+# of results instead of trusting result #1 (dashboards, "show me everything
+# about X" style queries). No reranking overhead.
 def quick_search(query, user_id):
     return client.search(
         query=query,
         filters={"user_id": user_id},
     )
 
-# Reranked search - good when result order matters
+# Precision path - use when only the top result reaches the user, e.g. an
+# agent that injects a single fact into a prompt. Reranking (see above)
+# re-scores every match and moves the closest one to position 1, at the
+# cost of ~150-200ms added latency.
 def standard_search(query, user_id):
     return client.search(
         query=query,
@@ -118,14 +125,19 @@ def standard_search(query, user_id):
 ```
 
 ```javascript JavaScript
-// Basic search - good for exploration
+// Fast path - use for exploratory search, or anywhere the user scans a list
+// of results instead of trusting result #1 (dashboards, "show me everything
+// about X" style queries). No reranking overhead.
 function quickSearch(query, userId) {
     return client.search(query, {
         filters: { user_id: userId },
     });
 }
 
-// Reranked search - good when result order matters
+// Precision path - use when only the top result reaches the user, e.g. an
+// agent that injects a single fact into a prompt. Reranking (see above)
+// re-scores every match and moves the closest one to position 1, at the
+// cost of ~150-200ms added latency.
 function standardSearch(query, userId) {
     return client.search(query, {
         filters: { user_id: userId },
@@ -135,6 +147,8 @@ function standardSearch(query, userId) {
 ```
 </CodeGroup>
 
+**What changes in the response:** both calls return the same fields on each memory (see the [Search Memories API reference](/api-reference/memory/search-memories) for the full response shape). The only difference is the *order* of the `results` array, the same effect shown in the [Reranking example above](#reranking): `quick_search` returns results ranked by raw similarity, `standard_search` returns the reranked order.
+
 ## Best Practices
 
 ### Do