JDSS/mem0
2
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

[docs] OSS Features , Overview , Brushup (#3676)

Browse Source
This commit is contained in:
Parth Sharma
2025-10-27 12:31:40 -07:00
committed by GitHub
parent 80c9139c5b
commit ee8955d08b
37 changed files with 1856 additions and 1696 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/open-source/features/reranker-search.mdx
+213 -218
View File
@@ -1,26 +1,58 @@
---
title: Reranker-Enhanced Search
description: 'Improve search relevance with reranking models in Mem0 1.0.0 '
description: Boost relevance by reordering vector hits with reranking models.
icon: "ranking-star"
---
<Info icon="sparkles">
**Mem0 1.0.0+** supports reranker-enhanced search, letting specialized models reorder vector hits so you deliver the most relevant memories.
Reranker-enhanced search adds a second scoring pass after vector retrieval so Mem0 can return the most relevant memories first. Enable it when keyword similarity alone misses nuance or when you need the highest-confidence context for an agent decision.
<Info>
**You’ll use this when…**
- Queries are nuanced and require semantic understanding beyond vector distance.
- Large memory collections produce too many near matches to review manually.
- You want consistent scoring across providers by delegating ranking to a dedicated model.
</Info>
## Overview
<Warning>
Reranking raises latency and, for hosted models, API spend. Benchmark with production traffic and define a fallback path for latency-sensitive requests.
</Warning>
Rerankers are specialized models that improve the quality of search results by reordering initially retrieved memories. They work as a second-stage ranking system that analyzes the semantic relationship between your query and retrieved memories to provide more relevant results.
<Note>
All configuration snippets translate directly to the TypeScript SDK—swap dictionaries for objects while keeping the same keys (`provider`, `config`, `rerank` flags).
</Note>
## How Reranking Works
---
1. **Initial Vector Search**: Retrieves candidate memories using vector similarity
2. **Reranking**: Specialized model analyzes query-memory relationships
3. **Reordering**: Results are reordered based on semantic relevance
4. **Enhanced Results**: Final results with improved relevance scores
## Feature anatomy
## Configuration
- **Initial vector search:** Retrieve candidate memories by similarity.
- **Reranker pass:** A specialized model scores each candidate against the original query.
- **Reordered results:** Mem0 sorts responses using the reranker’s scores before returning them.
- **Optional fallbacks:** Toggle reranking per request or disable it entirely if performance or cost becomes a concern.
### Basic Setup
<AccordionGroup>
<Accordion title="Supported providers">
- **[Cohere](/components/rerankers/models/cohere)** – Multilingual hosted reranker with API-based scoring.
- **[Sentence Transformer](/components/rerankers/models/sentence_transformer)** – Local Hugging Face cross-encoders for GPU or CPU.
- **[Hugging Face](/components/rerankers/models/huggingface)** – Bring any hosted or on-prem reranker model ID.
- **[LLM Reranker](/components/rerankers/models/llm_reranker)** – Use your preferred LLM (OpenAI, etc.) for prompt-driven scoring.
- **[Zero Entropy](/components/rerankers/models/zero_entropy)** – High-quality neural reranking tuned for retrieval tasks.
</Accordion>
<Accordion title="Provider comparison">
| Provider | Latency | Quality | Cost | Local deploy |
| --- | --- | --- | --- | --- |
| Cohere | Medium | High | API cost | ❌ |
| Sentence Transformer | Low | Good | Free | ✅ |
| Hugging Face | Low–Medium | Variable | Free | ✅ |
| LLM Reranker | High | Very high | API cost | Depends |
</Accordion>
</AccordionGroup>
---
## Configure it
### Basic setup
```python
from mem0 import Memory
@@ -38,50 +70,43 @@ config = {
m = Memory.from_config(config)
```
### Supported Providers
<Info icon="check">
Confirm `results["results"][0]["score"]` reflects the reranker output—if the field is missing, the reranker was not applied.
</Info>
Mem0 supports multiple reranking providers. See the complete documentation for each:
<Tip>
Set `top_k` to the smallest candidate pool that still captures relevant hits. Smaller pools keep reranking costs down.
</Tip>
- **[Cohere](../../components/rerankers/models/cohere)**: Enterprise-grade with multilingual support
- **[Sentence Transformer](../../components/rerankers/models/sentence_transformer)**: Local HuggingFace models
- **[Hugging Face](../../components/rerankers/models/huggingface)**: Custom models from HuggingFace
- **[LLM Reranker](../../components/rerankers/models/llm_reranker)**: Use any LLM for flexible scoring
- **[Zero Entropy](../../components/rerankers/models/zero_entropy)**: State-of-the-art neural reranking
#### Cohere Reranker
### Provider-specific options
```python
# Cohere reranker
config = {
"reranker": {
"provider": "cohere",
"config": {
"model": "rerank-english-v3.0",
"api_key": "your-cohere-api-key",
"top_k": 10, # Number of results to rerank
"top_k": 10,
"return_documents": True
}
}
}
```
#### Sentence Transformer Reranker
```python
# Sentence Transformer reranker
config = {
"reranker": {
"provider": "sentence_transformer",
"config": {
"model": "cross-encoder/ms-marco-MiniLM-L-6-v2",
"device": "cuda", # Use GPU if available
"device": "cuda",
"max_length": 512
}
}
}
```
#### Hugging Face Reranker
```python
# Hugging Face reranker
config = {
"reranker": {
"provider": "huggingface",
@@ -92,11 +117,8 @@ config = {
}
}
}
```
#### LLM-based Reranker
```python
# LLM-based reranker
config = {
"reranker": {
"provider": "llm_reranker",
@@ -114,70 +136,11 @@ config = {
}
```
## Usage Examples
<Note>
Keep authentication keys in environment variables when you plug these configs into production projects.
</Note>
### Basic Reranked Search
```python
# Reranking is enabled by default when configured
results = m.search(
"What are my food preferences?",
user_id="alice"
)
# Results are automatically reranked for better relevance
for result in results["results"]:
print(f"Memory: {result['memory']}")
print(f"Score: {result['score']}")
```
<Info icon="check">
Expect each result to include both the base vector score and an updated rerank score so you can compare quality improvements.
</Info>
### Controlling Reranking
```python
# Enable reranking explicitly
results_with_rerank = m.search(
"What movies do I like?",
user_id="alice",
rerank=True
)
# Disable reranking for this search
results_without_rerank = m.search(
"What movies do I like?",
user_id="alice",
rerank=False
)
# Compare the difference in results
print("With reranking:", len(results_with_rerank["results"]))
print("Without reranking:", len(results_without_rerank["results"]))
```
### Combining with Filters
```python
# Reranking works with metadata filtering
results = m.search(
"important work tasks",
user_id="alice",
filters={
"AND": [
{"category": "work"},
{"priority": {"gte": 7}}
]
},
rerank=True,
limit=20
)
```
## Advanced Configuration
### Complete Configuration Example
### Full stack example
```python
config = {
@@ -216,120 +179,165 @@ config = {
m = Memory.from_config(config)
```
### Async Support
<Info icon="check">
A quick search should now return results with both vector and reranker scores, letting you compare improvements immediately.
</Info>
### Async support
```python
from mem0 import AsyncMemory
# Reranking works with async operations
async_memory = AsyncMemory.from_config(config)
async def search_with_rerank():
results = await async_memory.search(
return await async_memory.search(
"What are my preferences?",
user_id="alice",
rerank=True
)
return results
# Use in async context
import asyncio
results = asyncio.run(search_with_rerank())
```
## Performance Considerations
<Info icon="check">
Inspect the async response to confirm reranking still applies; the scores should match the synchronous implementation.
</Info>
### When to Use Reranking
✅ **Good Use Cases:**
- Complex semantic queries
- Domain-specific searches
- When precision is more important than speed
- Large memory collections
- Ambiguous or nuanced queries
❌ **Avoid When:**
- Simple keyword matching
- Real-time applications with strict latency requirements
- Small memory collections
- High-frequency searches where cost matters
### Performance Optimization
### Tune performance and cost
```python
# Optimize reranking performance
# GPU-friendly local reranker configuration
config = {
"reranker": {
"provider": "sentence_transformer",
"config": {
"model": "cross-encoder/ms-marco-MiniLM-L-6-v2",
"device": "cuda", # Use GPU
"batch_size": 32, # Process in batches
"top_k": 10, # Limit candidates
"max_length": 256 # Reduce if appropriate
}
}
}
```
### Cost Management
```python
# For API-based rerankers like Cohere
config = {
"reranker": {
"provider": "cohere",
"config": {
"model": "rerank-english-v3.0",
"api_key": "your-cohere-api-key",
"top_k": 5, # Reduce to control API costs
"device": "cuda",
"batch_size": 32,
"top_k": 10,
"max_length": 256
}
}
}
# Use reranking selectively
# Smart toggle for hosted rerankers
def smart_search(query, user_id, use_rerank=None):
# Automatically decide when to use reranking
if use_rerank is None:
use_rerank = len(query.split()) > 3 # Complex queries only
use_rerank = len(query.split()) > 3
return m.search(query, user_id=user_id, rerank=use_rerank)
```
## Error Handling
<Tip>
Use heuristics (query length, user tier) to decide when to rerank so high-signal queries benefit without taxing every request.
</Tip>
### Handle failures gracefully
```python
try:
results = m.search(
"test query",
user_id="alice",
rerank=True
)
except Exception as e:
print(f"Reranking failed: {e}")
# Gracefully fall back to vector search
results = m.search(
"test query",
user_id="alice",
rerank=False
)
results = m.search("test query", user_id="alice", rerank=True)
except Exception as exc:
print(f"Reranking failed: {exc}")
results = m.search("test query", user_id="alice", rerank=False)
```
## Reranker Comparison
<Warning>
Always fall back to vector-only search—dropped queries introduce bigger accuracy issues than slightly less relevant ordering.
</Warning>
| Provider | Latency | Quality | Cost | Local Deploy |
|----------|---------|---------|------|--------------|
| Cohere | Medium | High | API Cost | ❌ |
| Sentence Transformer | Low | Good | Free | ✅ |
| Hugging Face | Low-Medium | Variable | Free | ✅ |
| LLM Reranker | High | Very High | API Cost | Depends |
### Migrate from v0.x
## Real-world Examples
```python
# Before: basic vector search
results = m.search("query", user_id="alice")
### Customer Support
# After: same API with reranking enabled via config
config = {
"reranker": {
"provider": "sentence_transformer",
"config": {
"model": "cross-encoder/ms-marco-MiniLM-L-6-v2"
}
}
}
m = Memory.from_config(config)
results = m.search("query", user_id="alice")
```
---
## See it in action
### Basic reranked search
```python
results = m.search(
"What are my food preferences?",
user_id="alice"
)
for result in results["results"]:
print(f"Memory: {result['memory']}")
print(f"Score: {result['score']}")
```
<Info icon="check">
Expect each result to list the reranker-adjusted score so you can compare ordering against baseline vector results.
</Info>
### Toggle reranking per request
```python
results_with_rerank = m.search(
"What movies do I like?",
user_id="alice",
rerank=True
)
results_without_rerank = m.search(
"What movies do I like?",
user_id="alice",
rerank=False
)
```
<Tip>
Log the reranked vs. non-reranked lists during rollout so stakeholders can see the improvement before enforcing it everywhere.
</Tip>
<Info icon="check">
You should see the same memories in both lists, but the reranked response will reorder them based on semantic relevance.
</Info>
### Combine with metadata filters
```python
results = m.search(
"important work tasks",
user_id="alice",
filters={
"AND": [
{"category": "work"},
{"priority": {"gte": 7}}
]
},
rerank=True,
limit=20
)
```
<Info icon="check">
Verify filtered reranked searches still respect every metadata clause—reranking only reorders candidates, it never bypasses filters.
</Info>
### Real-world playbooks
#### Customer support
```python
# Improve support ticket relevance
config = {
"reranker": {
"provider": "cohere",
@@ -342,7 +350,6 @@ config = {
m = Memory.from_config(config)
# Find relevant support cases
results = m.search(
"customer having login issues with mobile app",
agent_id="support_bot",
@@ -351,10 +358,13 @@ results = m.search(
)
```
### Content Recommendation
<Info icon="check">
Top results should highlight tickets matching the login issue context so agents can respond faster.
</Info>
#### Content recommendation
```python
# Better content matching
results = m.search(
"science fiction books with space exploration themes",
user_id="reader123",
@@ -368,10 +378,13 @@ for result in results["results"]:
print(f"Relevance: {result['score']:.3f}")
```
### Personal Assistant
<Info icon="check">
Expect high-scoring recommendations that match both the requested theme and any metadata limits you applied.
</Info>
#### Personal assistant
```python
# Enhanced personal queries
results = m.search(
"What restaurants did I enjoy last month that had good vegetarian options?",
user_id="foodie_user",
@@ -386,58 +399,40 @@ results = m.search(
)
```
## Migration Guide
<Tip>
Reuse this pattern for other lifestyle queries—swap the filters and prompt text without changing the rerank configuration.
</Tip>
### From v0.x (No Reranking)
<Note>
Each workflow keeps the same `m.search(...)` signature, so you can template these queries across agents with only the prompt and filters changing.
</Note>
```python
# v0.x - basic vector search
results = m.search("query", user_id="alice")
```
---
### To v1.0.0 (With Reranking)
## Verify the feature is working
```python
# Add reranker configuration
config = {
"reranker": {
"provider": "sentence_transformer",
"config": {
"model": "cross-encoder/ms-marco-MiniLM-L-6-v2"
}
}
}
- Inspect result payloads for both `score` (vector) and reranker scores; mismatched fields indicate the reranker didn’t execute.
- Track latency before and after enabling reranking to ensure SLAs hold.
- Review provider logs or dashboards for throttling or quota warnings.
- Run A/B comparisons (rerank on/off) to validate improved relevance before defaulting to reranked responses.
m = Memory.from_config(config)
---
# Same search API, better results
results = m.search("query", user_id="alice") # Automatically reranked
```
## Best practices
## Best Practices
1. **Start local:** Try Sentence Transformer models to prove value before paying for hosted APIs.
2. **Monitor latency:** Add metrics around reranker duration so you notice regressions quickly.
3. **Control spend:** Use `top_k` and selective toggles to cap hosted reranker costs.
4. **Keep a fallback:** Always catch reranker failures and continue with vector-only ordering.
5. **Experiment often:** Swap providers or models to find the best fit for your domain and language mix.
1. **Start Simple**: Begin with Sentence Transformers for local deployment
2. **Monitor Performance**: Track both relevance improvements and latency
3. **Cost Awareness**: Use API-based rerankers judiciously
4. **Selective Usage**: Apply reranking where it provides the most value
5. **Fallback Strategy**: Always handle reranking failures gracefully
6. **Test Different Models**: Experiment to find the best fit for your domain
<Info>
Reranker-enhanced search significantly improves result relevance. Start with a local model and upgrade to API-based solutions as your needs grow.
</Info>
---
<CardGroup cols={2}>
<Card
title="Configure Rerankers"
description="Review provider fields, defaults, and environment variables."
icon="settings"
href="/components/rerankers/config"
/>
<Card
title="Build a Custom LLM Reranker"
description="Combine reranking with tailored prompts and scoring logic."
icon="sparkles"
href="/components/rerankers/models/llm_reranker"
/>
<Card title="Configure Rerankers" icon="sliders" href="/components/rerankers/config">
Review provider fields, defaults, and environment variables before going live.
</Card>
<Card title="Build a Custom LLM Reranker" icon="sparkles" href="/components/rerankers/models/llm_reranker">
Extend scoring with prompt-tuned LLM rerankers for niche workflows.
</Card>
</CardGroup>