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

# Adaptive Retrieval

> Automatically determine the optimal number of search results based on relevance

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:

```bash theme={null}
# 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**:

```bash theme={null}
# 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

```bash theme={null}
# 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:

```bash theme={null}
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:

```bash theme={null}
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:

```bash theme={null}
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:

```bash theme={null}
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:

```bash theme={null}
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

```python theme={null}
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

```typescript theme={null}
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:

```bash theme={null}
memvid find memory.mv2 --query "authentication" --json
```

```json theme={null}
{
  "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:

```bash theme={null}
# 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:

```python theme={null}
# 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:

```python theme={null}
# 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:

```bash theme={null}
# 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:

```bash theme={null}
# 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:

```bash theme={null}
# 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

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

### With Hybrid Search

```bash theme={null}
# 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

```bash theme={null}
# 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:

```bash theme={null}
memvid find memory.mv2 --query "your search"
```

### Tune Based on Feedback

If you're getting too many results:

```bash theme={null}
--min-relevancy 0.6  # Raise threshold
--adaptive-strategy cliff  # Stricter cutoff
```

If you're missing results:

```bash theme={null}
--min-relevancy 0.3  # Lower threshold
--max-k 100  # Raise cap
```

### Monitor with JSON Output

Check adaptive decisions to understand behavior:

```bash theme={null}
memvid find memory.mv2 --query "term" --json | jq '.adaptive_info'
```

***

## Troubleshooting

### "Adaptive returns too few results"

1. Lower `min-relevancy`:
   ```bash theme={null}
   --min-relevancy 0.3
   ```

2. Increase `max-k`:
   ```bash theme={null}
   --max-k 100
   ```

3. Try `relative` strategy:
   ```bash theme={null}
   --adaptive-strategy relative
   ```

### "Adaptive returns too many results"

1. Raise `min-relevancy`:
   ```bash theme={null}
   --min-relevancy 0.7
   ```

2. Use `cliff` strategy:
   ```bash theme={null}
   --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:

```bash theme={null}
--no-adaptive --top-k 10
```

***

## Next Steps

<CardGroup cols={2}>
  <Card title="Search & Ask" icon="magnifying-glass" href="/cli/search-and-ask">
    Complete search command reference
  </Card>

  <Card title="Deduplication" icon="copy" href="/concepts/deduplication">
    How Memvid prevents duplicate content
  </Card>
</CardGroup>