Adaptive Retrieval

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:

Scenario	Fixed Top-K	Result
Few relevant docs	Returns 10	Noise in results
Many relevant docs	Returns 10	Missing 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

Strategy	Best For	Behavior
`combined`	General use	Balanced, adaptive
`relative`	Consistent corpora	% of top score
`absolute`	Known thresholds	Fixed cutoff
`cliff`	Clustered topics	Sharp drop detection
`elbow`	Gradual distributions	Curve 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

Exploratory Search

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:

Operation	Time 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

With Hybrid Search

# 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”

Lower min-relevancy:
--min-relevancy 0.3
Increase max-k:
--max-k 100
Try relative strategy:
--adaptive-strategy relative

“Adaptive returns too many results”

Raise min-relevancy:
--min-relevancy 0.7
Use cliff strategy:
--adaptive-strategy cliff
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

​The Problem with Fixed Top-K

​How Adaptive Retrieval Works

​CLI Usage

​Tuning Adaptive Behavior

​Adaptive Strategies

​Combined (Default)

​Relative

​Absolute

​Cliff

​Elbow

​Strategy Comparison

​SDK Usage

​Python

​Node.js

​Understanding Results

​When to Disable Adaptive

​Pagination

​Comparison

​RAG Context Building

​Tuning for Your Data

​High-Precision Needs

​High-Recall Needs

​Exploratory Search

​Performance Considerations

​Combining with Other Features

​With Sketch Pre-filtering

​With Hybrid Search

​With Time Filtering

​Best Practices

​Start with Defaults

​Tune Based on Feedback

​Monitor with JSON Output

​Troubleshooting

​”Adaptive returns too few results”

​“Adaptive returns too many results”

​”Results vary unexpectedly between queries”

​Next Steps

Search & Ask

Deduplication