Skip to main content
Instead of returning a fixed number of results (top-k), adaptive retrieval automatically determines how many results are truly relevant to your query. This prevents both information overload (too many irrelevant results) and information loss (cutting off relevant results).

​
The Problem with Fixed Top-K

Traditional search returns a fixed number of results: 
# Always returns 10 results, even if:
# - Only 3 are relevant (7 are noise)
# - 25 are relevant (15 are missed)
memvid find memory.mv2 --query "authentication" --top-k 10
This creates two problems:
ScenarioFixed Top-KResult
Few relevant docsReturns 10Noise in results
Many relevant docsReturns 10Missing relevant content

​
How Adaptive Retrieval Works

Adaptive retrieval analyzes the score distribution of results to find natural cutoff points: 
Score Distribution Example:

Result 1: 0.95  ████████████████████  ← Highly relevant
Result 2: 0.91  ███████████████████   ← Highly relevant
Result 3: 0.88  ██████████████████    ← Highly relevant
Result 4: 0.42  █████████             ← Score cliff detected!
Result 5: 0.38  ████████
Result 6: 0.35  ███████
...

Adaptive returns: Results 1-3 (stops at the cliff)

​
CLI Usage

Adaptive retrieval is enabled by default: 
# Adaptive mode (default)
memvid find memory.mv2 --query "authentication best practices"
# Returns: 3-15 results based on relevance distribution

# Disable adaptive, use fixed top-k
memvid find memory.mv2 --query "authentication" --no-adaptive --top-k 10
# Returns: Exactly 10 results

​
Tuning Adaptive Behavior

# Minimum relevance threshold (0.0-1.0)
memvid find memory.mv2 --query "security" --min-relevancy 0.6
# Only returns results with score >= 0.6

# Maximum results cap
memvid find memory.mv2 --query "config" --max-k 50
# Returns up to 50 results (fewer if cliff detected earlier)

# Choose strategy
memvid find memory.mv2 --query "api" --adaptive-strategy cliff
# Uses cliff detection algorithm

​
Adaptive Strategies

Five strategies are available for different use cases:

​
Combined (Default)

Balances multiple signals for best overall performance: 
memvid find memory.mv2 --query "term" --adaptive-strategy combined
  • Uses both relative and absolute thresholds
  • Applies cliff detection as secondary signal
  • Best for general-purpose search

​
Relative

Cuts off at a percentage of the top score: 
memvid find memory.mv2 --query "term" --adaptive-strategy relative
  • Default threshold: 50% of top score
  • Good for consistent corpora
  • Example: Top score 0.92 → cutoff at 0.46

​
Absolute

Uses a fixed score cutoff: 
memvid find memory.mv2 --query "term" --adaptive-strategy absolute --min-relevancy 0.5
  • Cuts at specified minimum score
  • Good when you know your quality threshold
  • Predictable behavior across queries

​
Cliff

Detects sharp drops in score distribution: 
memvid find memory.mv2 --query "term" --adaptive-strategy cliff
  • Looks for score drops > 30% between consecutive results
  • Best for distinct topic clusters
  • Works well when relevant docs are clearly separated

​
Elbow

Finds the inflection point in the score curve: 
memvid find memory.mv2 --query "term" --adaptive-strategy elbow
  • Uses curve analysis to find natural groupings
  • Good for gradual score distributions
  • Mathematically principled approach

​
Strategy Comparison

StrategyBest ForBehavior
combinedGeneral useBalanced, adaptive
relativeConsistent corpora% of top score
absoluteKnown thresholdsFixed cutoff
cliffClustered topicsSharp drop detection
elbowGradual distributionsCurve inflection

​
SDK Usage

​
Python

from memvid import use

mem = use('basic', 'memory.mv2')

# Adaptive (default)
results = mem.find("authentication patterns")
print(f"Returned {len(results)} relevant results")

# With custom settings
results = mem.find(
    "security best practices",
    adaptive=True,
    min_relevancy=0.5,
    max_k=25,
    adaptive_strategy="cliff"
)

# Disable adaptive
results = mem.find(
    "config files",
    adaptive=False,
    top_k=10
)

​
Node.js

import { use } from '@anthropics/memvid'

const mem = await use('basic', 'memory.mv2')

// Adaptive (default)
const results = await mem.find("authentication patterns")
console.log(`Returned ${results.length} relevant results`)

// With custom settings
const results = await mem.find("security", {
  adaptive: true,
  minRelevancy: 0.5,
  maxK: 25,
  adaptiveStrategy: "cliff"
})

// Disable adaptive
const results = await mem.find("config", {
  adaptive: false,
  topK: 10
})

​
Understanding Results

Adaptive retrieval adds metadata to help you understand decisions: 
memvid find memory.mv2 --query "authentication" --json

{
  "query": "authentication",
  "strategy": "combined",
  "results": [
    {
      "frame_id": "frame_001",
      "score": 0.94,
      "title": "OAuth2 Implementation Guide"
    },
    {
      "frame_id": "frame_002",
      "score": 0.89,
      "title": "JWT Token Handling"
    },
    {
      "frame_id": "frame_003",
      "score": 0.85,
      "title": "Session Management"
    }
  ],
  "adaptive_info": {
    "total_candidates": 150,
    "cutoff_score": 0.72,
    "cutoff_reason": "cliff_detected",
    "results_returned": 3
  }
}

​
When to Disable Adaptive

Some scenarios work better with fixed top-k:

​
Pagination

When paginating through results: 
# Page 1
memvid find memory.mv2 --query "logs" --no-adaptive --top-k 20

# Page 2 (use cursor)
memvid find memory.mv2 --query "logs" --no-adaptive --top-k 20 --cursor <cursor>

​
Comparison

When comparing result counts across queries: 
# Need consistent counts for comparison
results_a = mem.find("topic A", adaptive=False, top_k=50)
results_b = mem.find("topic B", adaptive=False, top_k=50)

coverage_a = len([r for r in results_a if r.score > 0.5])
coverage_b = len([r for r in results_b if r.score > 0.5])

​
RAG Context Building

When you need a specific context window: 
# Need exactly 5 chunks for context
results = mem.find(
    query,
    adaptive=False,
    top_k=5
)
context = "\n".join([r.text for r in results])

​
Tuning for Your Data

​
High-Precision Needs

For applications where false positives are costly: 
# Strict threshold
memvid find memory.mv2 --query "term" \
  --min-relevancy 0.7 \
  --adaptive-strategy absolute

​
High-Recall Needs

For applications where missing results is costly: 
# Lenient threshold with high cap
memvid find memory.mv2 --query "term" \
  --min-relevancy 0.3 \
  --max-k 100 \
  --adaptive-strategy relative
For browsing and discovery: 
# Combined strategy with moderate settings
memvid find memory.mv2 --query "term" \
  --min-relevancy 0.4 \
  --max-k 50 \
  --adaptive-strategy combined

​
Performance Considerations

Adaptive retrieval adds minimal overhead:
OperationTime Added
Score analysis< 1ms
Cutoff detection< 1ms
Total overhead< 2ms
The algorithm runs on the score array after retrieval, so it doesn’t slow down the actual search.

​
Combining with Other Features

​
With Sketch Pre-filtering

# Sketches + adaptive = fast + precise
memvid sketch build memory.mv2 --variant medium
memvid find memory.mv2 --query "term"  # Both enabled by default

# Adaptive works with all search modes
memvid find memory.mv2 --query "term" --mode auto  # Hybrid + adaptive
memvid find memory.mv2 --query "term" --mode lex   # Lexical + adaptive
memvid find memory.mv2 --query "term" --mode sem   # Semantic + adaptive

​
With Time Filtering

# Adaptive respects filters
memvid find memory.mv2 --query "report" \
  --start 2024-01-01 \
  --end 2024-06-30 \
  --adaptive-strategy cliff

​
Best Practices

​
Start with Defaults

The default combined strategy works well for most cases: 
memvid find memory.mv2 --query "your search"

​
Tune Based on Feedback

If you’re getting too many results: 
--min-relevancy 0.6  # Raise threshold
--adaptive-strategy cliff  # Stricter cutoff
If you’re missing results: 
--min-relevancy 0.3  # Lower threshold
--max-k 100  # Raise cap

​
Monitor with JSON Output

Check adaptive decisions to understand behavior: 
memvid find memory.mv2 --query "term" --json | jq '.adaptive_info'

​
Troubleshooting

​
”Adaptive returns too few results”

  1. Lower min-relevancy: 
    --min-relevancy 0.3
  2. Increase max-k: 
    --max-k 100
  3. Try relative strategy: 
    --adaptive-strategy relative

​
“Adaptive returns too many results”

  1. Raise min-relevancy: 
    --min-relevancy 0.7
  2. Use cliff strategy: 
    --adaptive-strategy cliff
  3. Consider if your query is too broad

​
”Results vary unexpectedly between queries”

This is expected - adaptive adjusts to each query’s score distribution. For consistent counts, use: 
--no-adaptive --top-k 10

​
Next Steps

Search & Ask

Complete search command reference

Deduplication

How Memvid prevents duplicate content