Documentation Index Fetch the complete documentation index at: https://docs.memvid.com/llms.txt
Use this file to discover all available pages before exploring further.
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 combinedGeneral use Balanced, adaptive relativeConsistent corpora % of top score absoluteKnown thresholds Fixed cutoff cliffClustered topics Sharp drop detection elbowGradual 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:
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 < curso r >
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
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:
Increase max-k:
Try relative strategy:
--adaptive-strategy relative
“Adaptive returns too many results”
Raise min-relevancy:
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:
Next Steps
Search & Ask Complete search command reference
Deduplication How Memvid prevents duplicate content
