feat(oss): add reranker + per-search rerank to the TypeScript OSS SDK (#6055)

This commit is contained in:
Kartik
2026-07-09 22:18:38 +05:30
committed by GitHub
parent 2a4aa232b2
commit 6a801bfe2f
32 changed files with 2173 additions and 19 deletions
+28 -1
View File
@@ -26,7 +26,7 @@ All rerankers share these common configuration parameters:
| Parameter | Description | Type | Default |
| -------------------- | -------------------------------------------- | ------ | ----------------------- |
| `model` | Cohere rerank model | `str` | `"rerank-english-v3.0"` |
| `model` | Cohere rerank model | `str` | `"rerank-v3.5"` |
| `api_key` | Cohere API key | `str` | `None` |
| `return_documents` | Whether to return document texts in response | `bool` | `False` |
| `max_chunks_per_doc` | Maximum chunks per document | `int` | `None` |
@@ -103,3 +103,30 @@ config = {
}
}
```
## TypeScript SDK
The self-hosted [TypeScript SDK](/open-source/features/reranker-search#typescript-sdk) (`mem0ai/oss`) supports the same five providers. Config keys are camelCase (`apiKey`, `topK`, `maxLength`) and each provider's SDK is a peer dependency you install per reranker.
| Provider | Install | Default model | Key config fields |
| --- | --- | --- | --- |
| `cohere` | `pnpm add cohere-ai` | `rerank-v3.5` | `apiKey`, `model`, `topK` |
| `zero_entropy` | `pnpm add zeroentropy` | `zerank-1` | `apiKey`, `model`, `topK` |
| `sentence_transformer` | `pnpm add @huggingface/transformers` | `Xenova/ms-marco-MiniLM-L-6-v2` | `model`, `device`, `maxLength`, `normalize`, `topK` |
| `huggingface` | `pnpm add @huggingface/transformers` | `Xenova/bge-reranker-base` | `model`, `device`, `maxLength`, `normalize`, `topK` |
| `llm_reranker` | — (uses your LLM provider's own SDK) | `openai` / `gpt-4o-mini` | `provider`, `model`, `apiKey`, `llm` (nested override), `topK` |
```typescript
import { Memory } from "mem0ai/oss";
const memory = new Memory({
reranker: {
provider: "zero_entropy",
config: { apiKey: process.env.ZERO_ENTROPY_API_KEY, topK: 5 },
},
});
```
<Note>
The local cross-encoder providers (`sentence_transformer`, `huggingface`) run on [Transformers.js](https://huggingface.co/docs/transformers.js) and default to ONNX (`Xenova/*`) model mirrors, so Python default model strings must be swapped for their ONNX equivalents. `batchSize` and `showProgressBar` are accepted for parity with Python but are no-ops in the TypeScript runtime. See the [reranker feature guide](/open-source/features/reranker-search#typescript-sdk) for full examples.
</Note>
+35 -7
View File
@@ -9,9 +9,9 @@ Cohere provides enterprise-grade reranking models with excellent multilingual su
Cohere offers several reranking models:
- **`rerank-english-v3.0`**: Latest English reranker with best performance
- **`rerank-multilingual-v3.0`**: Multilingual support for global applications
- **`rerank-english-v2.0`**: Previous generation English reranker
- **`rerank-v3.5`** (default): Latest reranker, multilingual, best performance
- **`rerank-english-v3.0`**: Previous generation, English only
- **`rerank-multilingual-v3.0`**: Previous generation, multilingual
## Installation
@@ -41,7 +41,7 @@ config = {
"reranker": {
"provider": "cohere",
"config": {
"model": "rerank-english-v3.0",
"model": "rerank-v3.5",
"api_key": "your-cohere-api-key", # or set COHERE_API_KEY
"top_k": 5,
"return_documents": False,
@@ -53,6 +53,34 @@ config = {
memory = Memory.from_config(config)
```
## TypeScript (self-hosted)
The [TypeScript OSS SDK](/open-source/features/reranker-search#typescript-sdk) (`mem0ai/oss`) ships the Cohere reranker. Config keys are camelCase, it defaults to the `rerank-v3.5` model, and you opt in per search with `rerank: true`.
```bash
pnpm add cohere-ai
```
```typescript
import { Memory } from "mem0ai/oss";
const memory = new Memory({
reranker: {
provider: "cohere",
config: {
apiKey: process.env.COHERE_API_KEY, // or set COHERE_API_KEY
// model: "rerank-v3.5", // default
topK: 5,
},
},
});
const results = await memory.search("What is the user's profession?", {
filters: { userId: "bob" },
rerank: true,
});
```
## Environment Variables
Set your API key as an environment variable:
@@ -77,7 +105,7 @@ config = {
"rerank": {
"provider": "cohere",
"config": {
"model": "rerank-english-v3.0",
"model": "rerank-v3.5",
"top_k": 3
}
}
@@ -124,7 +152,7 @@ config = {
| Parameter | Description | Type | Default |
| -------------------- | -------------------------------- | ------ | ----------------------- |
| `model` | Cohere rerank model to use | `str` | `"rerank-english-v3.0"` |
| `model` | Cohere rerank model to use | `str` | `"rerank-v3.5"` |
| `api_key` | Cohere API key | `str` | `None` |
| `top_k` | Maximum documents to return | `int` | `None` |
| `return_documents` | Whether to return document texts | `bool` | `False` |
@@ -139,7 +167,7 @@ config = {
## Best Practices
1. **Model Selection**: Use `rerank-english-v3.0` for English, `rerank-multilingual-v3.0` for other languages
1. **Model Selection**: `rerank-v3.5` handles English and multilingual workloads; pin an older `v3.0` model only if you need to reproduce prior results
2. **Batch Processing**: Process multiple queries efficiently
3. **Error Handling**: Implement retry logic for production systems
4. **Monitoring**: Track reranking performance and costs
@@ -57,6 +57,40 @@ config = {
}
```
## TypeScript (self-hosted)
The [TypeScript OSS SDK](/open-source/features/reranker-search#typescript-sdk) (`mem0ai/oss`) runs this reranker locally with [Transformers.js](https://huggingface.co/docs/transformers.js) — the same cross-encoder path as `sentence_transformer`, just a different default model. It executes ONNX weights, so the default is the ONNX mirror `Xenova/bge-reranker-base`. Point `model` at any ONNX-exported reranker on the Hub (a raw `BAAI/bge-reranker-*` PyTorch checkpoint will not load in this runtime).
```bash
pnpm add @huggingface/transformers
```
```typescript
import { Memory } from "mem0ai/oss";
const memory = new Memory({
reranker: {
provider: "huggingface",
config: {
// model: "Xenova/bge-reranker-base", // default (ONNX)
device: "cpu", // "cpu" | "wasm" | "webgpu"
maxLength: 512, // max tokens per query-document pair
normalize: true, // sigmoid-normalize logits to [0, 1] (default)
topK: 5,
},
},
});
const results = await memory.search("What are the user's interests?", {
filters: { userId: "alice" },
rerank: true,
});
```
<Note>
`batchSize` and `showProgressBar` are accepted for parity with the Python SDK but are no-ops in the TypeScript runtime. `trust_remote_code` and `model_kwargs` are Python-only.
</Note>
## Popular Models
### BGE Rerankers (Recommended)
@@ -67,6 +67,43 @@ config = {
}
```
## TypeScript (self-hosted)
The [TypeScript OSS SDK](/open-source/features/reranker-search#typescript-sdk) (`mem0ai/oss`) ships the LLM reranker under the provider name `llm_reranker`. It does **not** reuse the Memory's main `llm` instance — it builds its own LLM from the reranker's own config, defaulting to `openai` / `gpt-4o-mini`. Set `provider`/`model`/`apiKey` directly on `config`, or nest a fully separate `config.llm: { provider, config }` (its `provider`/`config` take priority over the top-level fields, which only backfill values missing from the nested config).
```typescript
import { Memory } from "mem0ai/oss";
const memory = new Memory({
reranker: {
provider: "llm_reranker",
config: { apiKey: process.env.OPENAI_API_KEY },
},
});
const results = await memory.search("What movies do I like?", {
filters: { userId: "alice" },
rerank: true,
});
```
To rerank with a different LLM provider than the Memory's main `llm`, nest it under `config.llm`:
```typescript
const memory = new Memory({
llm: { provider: "openai", config: { apiKey: process.env.OPENAI_API_KEY } },
reranker: {
provider: "llm_reranker",
config: {
llm: {
provider: "anthropic",
config: { apiKey: process.env.ANTHROPIC_API_KEY },
},
},
},
});
```
## Supported LLM Providers
### OpenAI
@@ -54,6 +54,40 @@ config = {
memory = Memory.from_config(config)
```
## TypeScript (self-hosted)
The [TypeScript OSS SDK](/open-source/features/reranker-search#typescript-sdk) (`mem0ai/oss`) runs this reranker locally with [Transformers.js](https://huggingface.co/docs/transformers.js). Because it executes ONNX weights, the default model is the ONNX mirror of the Python default — `Xenova/ms-marco-MiniLM-L-6-v2`. Point `model` at any ONNX-exported cross-encoder on the Hub (a raw `cross-encoder/...` PyTorch checkpoint will not load in this runtime).
```bash
pnpm add @huggingface/transformers
```
```typescript
import { Memory } from "mem0ai/oss";
const memory = new Memory({
reranker: {
provider: "sentence_transformer",
config: {
// model: "Xenova/ms-marco-MiniLM-L-6-v2", // default (ONNX)
device: "cpu", // "cpu" | "wasm" | "webgpu"
maxLength: 512, // max tokens per query-document pair
normalize: true, // sigmoid-normalize logits to [0, 1] (default)
topK: 5,
},
},
});
const results = await memory.search("What books does the user like?", {
filters: { userId: "charlie" },
rerank: true,
});
```
<Note>
`batchSize` and `showProgressBar` are accepted for parity with the Python SDK but are no-ops in the TypeScript runtime — a search reranks a small candidate set in a single in-process forward pass. The model downloads once and is cached in-process.
</Note>
## GPU Acceleration
For better performance, use GPU acceleration:
@@ -50,6 +50,34 @@ config = {
memory = Memory.from_config(config)
```
## TypeScript (self-hosted)
The [TypeScript OSS SDK](/open-source/features/reranker-search#typescript-sdk) (`mem0ai/oss`) ships the Zero Entropy reranker under the same provider name as Python, `zero_entropy`. It reads the key from config or `ZERO_ENTROPY_API_KEY` and defaults to the `zerank-1` model.
```bash
pnpm add zeroentropy
```
```typescript
import { Memory } from "mem0ai/oss";
const memory = new Memory({
reranker: {
provider: "zero_entropy",
config: {
apiKey: process.env.ZERO_ENTROPY_API_KEY,
// model: "zerank-1", // default (or "zerank-1-small")
topK: 5,
},
},
});
const results = await memory.search("What Italian food does the user like?", {
filters: { userId: "alice" },
rerank: true,
});
```
## Environment Variables
Set your API key as an environment variable:
+2 -2
View File
@@ -47,7 +47,7 @@ config = {
"reranker": {
"provider": "cohere",
"config": {
"model": "rerank-english-v3.0",
"model": "rerank-v3.5",
"top_n": 10,
"max_chunks_per_doc": 10, # Limit chunk processing
"return_documents": False # Reduce response size
@@ -280,7 +280,7 @@ config = {
```python
def benchmark_rerankers():
configs = [
{"provider": "cohere", "model": "rerank-english-v3.0"},
{"provider": "cohere", "model": "rerank-v3.5"},
{"provider": "sentence_transformer", "model": "cross-encoder/ms-marco-MiniLM-L-6-v2"},
{"provider": "huggingface", "model": "BAAI/bge-reranker-base"}
]
+4
View File
@@ -19,6 +19,10 @@ Reranking trades extra latency for better precision. Start once you have baselin
<Card title="Zero Entropy" icon="/images/provider-icons/zeroentropy.svg" href="/components/rerankers/models/zero_entropy" />
</CardGroup>
<Note>
All five rerankers are available in both the Python and the [TypeScript](/open-source/features/reranker-search#typescript-sdk) self-hosted SDKs. Each provider page has a **TypeScript (self-hosted)** section with the camelCase config.
</Note>
## Reranking Workflow
<CardGroup cols={3}>
+2 -1
View File
@@ -501,5 +501,6 @@ Everything below is OSS-only provider configuration. Skip this entire section wh
- [Custom Reranker Prompts](https://docs.mem0.ai/components/rerankers/custom-prompts) [OSS]: Use when rewriting reranker prompts.
- [Cohere Reranker](https://docs.mem0.ai/components/rerankers/models/cohere) [OSS]: Use for Cohere Rerank.
- [Sentence Transformer Reranker](https://docs.mem0.ai/components/rerankers/models/sentence_transformer) [OSS]: Use for local cross-encoder rerankers.
- [Hugging Face Reranker](https://docs.mem0.ai/components/rerankers/models/huggingface) [OSS]: Use for HF-hosted reranker models.- [LLM Reranker](https://docs.mem0.ai/components/rerankers/models/llm_reranker) [OSS]: Use when the reranker is a prompted LLM (implementation reference).
- [Hugging Face Reranker](https://docs.mem0.ai/components/rerankers/models/huggingface) [OSS]: Use for HF-hosted reranker models.
- [LLM Reranker](https://docs.mem0.ai/components/rerankers/models/llm_reranker) [OSS]: Use when the reranker is a prompted LLM (implementation reference).
- [Zero Entropy Reranker](https://docs.mem0.ai/components/rerankers/models/zero_entropy) [OSS]: Use for the Zero Entropy reranker.
+1 -1
View File
@@ -59,7 +59,7 @@ config = {
},
"reranker": {
"provider": "cohere",
"config": {"model": "rerank-english-v3.0"},
"config": {"model": "rerank-v3.5"},
},
}
+127 -5
View File
@@ -18,7 +18,129 @@ Reranker-enhanced search adds a second scoring pass after vector retrieval so Me
</Warning>
<Note>
All configuration snippets translate directly to the TypeScript SDK: swap dictionaries for objects while keeping the same keys (`provider`, `config`, `rerank` flags).
The `Configure it` and `See it in action` snippets below use the Python SDK. The self-hosted **TypeScript SDK** supports the Cohere, Zero Entropy, Sentence Transformer, Hugging Face, and LLM rerankers — see [TypeScript SDK](#typescript-sdk).
</Note>
---
## TypeScript SDK
The self-hosted TypeScript SDK (`mem0ai/oss`) ships five rerankers: **Cohere**, **Zero Entropy**, **Sentence Transformer**, **Hugging Face**, and the **LLM reranker**. Configure one under `reranker`, then opt in per search with `rerank: true`. Keys are camelCase (`apiKey`, not `api_key`).
Provider SDKs are peer dependencies — install the one your reranker needs:
```bash
pnpm add cohere-ai # cohere
pnpm add zeroentropy # zero_entropy
pnpm add @huggingface/transformers # sentence_transformer, huggingface
# llm_reranker defaults to openai (already a core dependency) — install another
# provider's SDK only if you nest a different one under config.llm
```
### Hosted rerankers (Cohere, Zero Entropy)
Both call a hosted API and read their key from config or the provider's environment variable (`COHERE_API_KEY`, `ZERO_ENTROPY_API_KEY`).
```typescript
import { Memory } from "mem0ai/oss";
// Cohere reranker (defaults to the rerank-v3.5 model)
const memory = new Memory({
reranker: {
provider: "cohere",
config: { apiKey: process.env.COHERE_API_KEY },
},
});
const results = await memory.search("What are my food preferences?", {
filters: { userId: "alice" },
rerank: true,
});
```
```typescript
// Zero Entropy reranker (defaults to the zerank-1 model)
const memory = new Memory({
reranker: {
provider: "zero_entropy",
config: { apiKey: process.env.ZERO_ENTROPY_API_KEY },
},
});
```
### Local cross-encoders (Sentence Transformer, Hugging Face)
Both run a cross-encoder locally with [Transformers.js](https://huggingface.co/docs/transformers.js) — no API key, no network at inference time. Because Transformers.js runs ONNX weights, the default models are the ONNX mirrors of the Python SDK's defaults (`sentence_transformer` → `Xenova/ms-marco-MiniLM-L-6-v2`, `huggingface` → `Xenova/bge-reranker-base`). Point `model` at any ONNX-exported cross-encoder on the Hub to override.
```typescript
const memory = new Memory({
reranker: {
provider: "sentence_transformer", // or "huggingface"
config: {
// model: "Xenova/bge-reranker-base", // override the default
device: "cpu", // Transformers.js device: "cpu" | "wasm" | "webgpu"
maxLength: 512, // max tokens per query-document pair
normalize: true, // sigmoid-normalize logits to [0, 1] (default)
},
},
});
const results = await memory.search("What movies do I like?", {
filters: { userId: "alice" },
rerank: true,
});
```
<Note>
`batchSize` and `showProgressBar` are accepted for config parity with the Python SDK but are no-ops in this runtime — a memory search reranks a small candidate set in a single in-process forward pass. The model is downloaded once and cached in-process on first use.
</Note>
### LLM reranker
To score with an LLM instead of a dedicated reranker, use the `llm_reranker` provider. It builds its own LLM from the reranker's config — defaulting to `openai` / `gpt-4o-mini` — rather than reusing the Memory's main `llm`:
```typescript
const memory = new Memory({
reranker: {
provider: "llm_reranker",
config: { apiKey: process.env.OPENAI_API_KEY },
},
});
const results = await memory.search("What movies do I like?", {
filters: { userId: "alice" },
rerank: true,
});
```
Nest a different provider under `config.llm` to override the default:
```typescript
const memory = new Memory({
reranker: {
provider: "llm_reranker",
config: {
llm: {
provider: "anthropic",
config: { apiKey: process.env.ANTHROPIC_API_KEY },
},
},
},
});
```
### Config reference
| Provider | Default model | Key config fields |
| --- | --- | --- |
| `cohere` | `rerank-v3.5` | `apiKey`, `model`, `topK` |
| `zero_entropy` | `zerank-1` | `apiKey`, `model`, `topK` |
| `sentence_transformer` | `Xenova/ms-marco-MiniLM-L-6-v2` | `model`, `device`, `maxLength`, `normalize`, `topK` |
| `huggingface` | `Xenova/bge-reranker-base` | `model`, `device`, `maxLength`, `normalize`, `topK` |
| `llm_reranker` | `openai` / `gpt-4o-mini` | `provider`, `model`, `apiKey`, `llm` (nested override), `topK` |
<Note>
`rerank` is opt-in per search and a no-op when no `reranker` is configured. If the reranker call fails, Mem0 logs a warning and returns the original vector-ranked results.
</Note>
---
@@ -61,7 +183,7 @@ config = {
"reranker": {
"provider": "cohere",
"config": {
"model": "rerank-english-v3.0",
"model": "rerank-v3.5",
"api_key": "your-cohere-api-key"
}
}
@@ -86,7 +208,7 @@ config = {
"reranker": {
"provider": "cohere",
"config": {
"model": "rerank-english-v3.0",
"model": "rerank-v3.5",
"api_key": "your-cohere-api-key",
"top_k": 10,
"return_documents": True
@@ -164,7 +286,7 @@ config = {
"reranker": {
"provider": "cohere",
"config": {
"model": "rerank-english-v3.0",
"model": "rerank-v3.5",
"api_key": "your-cohere-api-key",
"top_k": 15,
"return_documents": True
@@ -338,7 +460,7 @@ config = {
"reranker": {
"provider": "cohere",
"config": {
"model": "rerank-english-v3.0",
"model": "rerank-v3.5",
"api_key": "your-cohere-api-key"
}
}