vector-index-tuning

Use it when:: A vector index is too slow, too large, or not recalling enough, and you need to tune it.
It does:: Maps data size to an index type and explains the HNSW parameters and quantization options that trade recall against speed and memory.
You get:: A tuning plan; a reference file holds the templates and worked examples.
Knobs:: HNSW's M, efConstruction and efSearch; and FP16, INT8, product or binary quantization for memory savings.

TL;DR

A reference for optimizing vector indexes in production. The SKILL.md maps data size to an index: flat exact search under 10K vectors, HNSW to 1M, HNSW with quantization to 100M, IVF+PQ or DiskANN beyond that. It explains the three HNSW parameters — M (connections per node), efConstruction (build quality) and efSearch (search quality) — each trading recall against memory or speed, and lists quantization options from full FP32 down through FP16, INT8 scalar, product quantization and binary, with their byte costs. Its advice: benchmark with real queries not synthetic, monitor recall continuously because data drift degrades it, start from defaults and tune only when needed, use quantization for large memory savings, consider tiered hot/cold storage, profile before optimizing, account for build and reindex time, and warm a cold index. The concrete templates and worked examples live in a reference file.

Summarizes the skill at 4bde316.

npx skills add https://github.com/wshobson/agents --skill vector-index-tuning

skills.sh page Source on GitHub All skills from wshobson/agents

Total Downloads: 11,000 on skills.sh, Nov 9, 2026
Repo stars: 42,334 wshobson/agents
First seen: Jan 20, 2026 on skills.sh

Weekly Downloads

148

-18% over the 8 weeks to Nov 9

Weekly values

Week to	Installs
Sep 21	180
Sep 28	213
Oct 5	265
Oct 12	208
Oct 19	179
Oct 26	180
Nov 2	169
Nov 9	148

Category	category:agents category:software-engineering Build agents, orchestrate workers and give agents memory. Everything for building software: planning, coding, debugging, design, frameworks, cloud, agents and skills.
Type	type:guidelines Knowledge and rules the agent applies while it works: best practices, design principles, API references.
Effect	effect:none Adds no side effects of its own. It shapes how the agent thinks, writes or reviews. Guidelines and routers are always effect:none, even when the task they support edits code.
Needs	needs:none Instructions only. Works in any agent that supports skills.
Publisher	by:community Everyone else. Unverified vendor claims default to community.
Topics	databases performance agent-development

SKILL.md

From wshobson/agents at 4bde316. Checked daily, last changed Nov 6, 2026.

Frontmatter

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

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