---

name: backends-and-storage description: "Choose, configure, validate, and troubleshoot LEANN vector backends, index artifacts, and selective embedding recomputation." disable-model-invocation: true metadata: disco-role: operating license: MIT

Backends and storage

Use this sub-skill when the task changes the vector index backend, storage mode, search graph, optional accelerator, or recomputation path. Keep ordinary embedding/provider and end-to-end API/CLI instructions in their sibling sub-skills.

Route by decision

1. Choose a backend or plan an update: backend selection.
2. Identify files, passage offsets, or recomputation behavior: artifacts and recomputation.
3. Tune graph/IVF search, pruning, beam, or metric compatibility: backend tuning.
4. Evaluate DiskANN or CUDA FlashLib variants: optional accelerator backends.
5. Diagnose a failed install, build, search, or incomplete index: troubleshooting.
6. Validate an existing index without changing it: python scripts/inspect_leann_index.py INDEX_PATH.

Non-negotiable invariants

• The installed distribution names (leann-backend-*) and registry names are different; use the exact registry name in LEANN configuration.
• The embedding dimension and distance metric recorded in .meta.json must agree with the vectors and backend artifact. Normalized vectors need the cosine-compatible path described in the tuning reference.
• Compact/pruned HNSW is a storage format, not an update format: it requires recomputation for search and must be rebuilt for in-place changes.
• IVF is the CPU modification-oriented option: it uses FAISS IndexIVFFlat with DirectMap.Hashtable, and updates remove old IDs before adding new ones.
• DiskANN and both FlashLib variants are optional in this verified environment; never turn their documentation into a local availability or performance promise. The inspector checks files only and does not prove native/GPU search.

The bundled inspector is read-only, uses no model/network/credential, and exits nonzero for invalid metadata, passage-offset mappings, or required backend artifacts. See the references for the exact checks and known limits.