Vector Index Tuning

Vector index tuning

by wshobson · MIT license · ★ 39,857 on GitHub · updated Sep 21

Optimize vector index performance for latency, recall, and memory. Use when tuning HNSW parameters, selecting quantization strategies, or scaling vector search infrastructure.

---
name: vector-index-tuning
description: Optimize vector index performance for latency, recall, and memory. Use when tuning HNSW parameters, selecting quantization strategies, or scaling vector search infrastructure.
---

# Vector Index Tuning

Guide to optimizing vector indexes for production performance.

## When to Use This Skill

- Tuning HNSW parameters
- Implementing quantization
- Optimizing memory usage
- Reducing search latency
- Balancing recall vs speed
- Scaling to billions of vectors

Overview

Guide to optimizing vector indexes for production performance.

Manual install (npx, ZIP)

Claude Codenpx skills add wshobson/agents --skill vector-index-tuning -g -a claude-code

Claude Code (manual)

mkdir -p ~/.claude/skills && curl -sL https://codeload.github.com/wshobson/agents/tar.gz/4236bb91f839 \
  | tar -xz -C ~/.claude/skills --strip-components=4 agents-4236bb91f839/plugins/llm-application-dev/skills/vector-index-tuning

Windows (PowerShell)

New-Item -ItemType Directory -Force "$HOME\.claude\skills" | Out-Null; Invoke-WebRequest "https://m.agentalley.io/zip/bde3a85d27303ac2c78c/vector-index-tuning.zip" -OutFile "$env:TEMP\vector-index-tuning.zip"; Expand-Archive "$env:TEMP\vector-index-tuning.zip" -DestinationPath "$HOME\.claude\skills" -Force

Claude.ai / desktopDownload the ZIP and upload it under Settings → Capabilities → Skills.

Codex, Cursor, other agentsPoint them at SKILL.md. The other files are plain text.

Connects with Agent Alley MCP · agentalley.io/mcp

Files included

SKILL.md2.3 KB
references/1 file · 12.9 KB

Read the files here

wshobson/4236bb92 files

SKILL.md2.3 KB

SKILL.md

Show the full text70 lines

vector-index-tuning/SKILL.md70 lines · 2.3 KB

PreviewCode

Outline

RawView on GitHub

Vector Index Tuning

Guide to optimizing vector indexes for production performance.

When to Use This Skill

Tuning HNSW parameters
Implementing quantization
Optimizing memory usage
Reducing search latency
Balancing recall vs speed
Scaling to billions of vectors

Core Concepts

1. Index Type Selection

Data Size           Recommended Index
────────────────────────────────────────
< 10K vectors  →    Flat (exact search)
10K - 1M       →    HNSW
1M - 100M      →    HNSW + Quantization
> 100M         →    IVF + PQ or DiskANN

2. HNSW Parameters

Parameter	Default	Effect
M	16	Connections per node, ↑ = better recall, more memory
efConstruction	100	Build quality, ↑ = better index, slower build
efSearch	50	Search quality, ↑ = better recall, slower search

3. Quantization Types

Full Precision (FP32): 4 bytes × dimensions
Half Precision (FP16): 2 bytes × dimensions
INT8 Scalar:           1 byte × dimensions
Product Quantization:  ~32-64 bytes total
Binary:                dimensions/8 bytes

Templates and detailed worked examples

Full template library and detailed worked examples live in references/details.md. Read that file when you need the concrete templates.

Best Practices

Do's

Benchmark with real queries - Synthetic may not represent production
Monitor recall continuously - Can degrade with data drift
Start with defaults - Tune only when needed
Use quantization - Significant memory savings
Consider tiered storage - Hot/cold data separation

Don'ts

Don't over-optimize early - Profile first
Don't ignore build time - Index updates have cost
Don't forget reindexing - Plan for maintenance
Don't skip warming - Cold indexes are slow

1	---
2	name: vector-index-tuning
3	description: Optimize vector index performance for latency, recall, and memory. Use when tuning HNSW parameters, selecting quantization strategies, or scaling vector search infrastructure.
4	---
5
6	# Vector Index Tuning
7
8	Guide to optimizing vector indexes for production performance.
9
10	## When to Use This Skill
11
12	- Tuning HNSW parameters
13	- Implementing quantization
14	- Optimizing memory usage
15	- Reducing search latency
16	- Balancing recall vs speed
17	- Scaling to billions of vectors
18
19	## Core Concepts
20
21	### 1. Index Type Selection
22
23	```
24	Data Size Recommended Index
25	────────────────────────────────────────
26	< 10K vectors → Flat (exact search)
27	10K - 1M → HNSW
28	1M - 100M → HNSW + Quantization
29	> 100M → IVF + PQ or DiskANN
30	```
31
32	### 2. HNSW Parameters
33
34	\| Parameter \| Default \| Effect \|
35	\| ------------------ \| ------- \| ---------------------------------------------------- \|
36	\| M \| 16 \| Connections per node, ↑ = better recall, more memory \|
37	\| efConstruction \| 100 \| Build quality, ↑ = better index, slower build \|
38	\| efSearch \| 50 \| Search quality, ↑ = better recall, slower search \|
39
40	### 3. Quantization Types
41
42	```
43	Full Precision (FP32): 4 bytes × dimensions
44	Half Precision (FP16): 2 bytes × dimensions
45	INT8 Scalar: 1 byte × dimensions
46	Product Quantization: ~32-64 bytes total
47	Binary: dimensions/8 bytes
48	```
49
50	## Templates and detailed worked examples
51
52	Full template library and detailed worked examples live in `references/details.md`. Read that file when you need the concrete templates.
53
54	## Best Practices
55
56	### Do's
57
58	- Benchmark with real queries - Synthetic may not represent production
59	- Monitor recall continuously - Can degrade with data drift
60	- Start with defaults - Tune only when needed
61	- Use quantization - Significant memory savings
62	- Consider tiered storage - Hot/cold data separation
63
64	### Don'ts
65
66	- Don't over-optimize early - Profile first
67	- Don't ignore build time - Index updates have cost
68	- Don't forget reindexing - Plan for maintenance
69	- Don't skip warming - Cold indexes are slow
70