Skip to main content

Indexing

Indexing is what makes semantic and hybrid retrieval useful. Prefer indexing a specific project instead of all roots unless you actually need cross-project retrieval.

localnest_index_status​

Returns whether semantic index data exists and which backend is active.

When using the JSON backend on larger indexes, this response includes:

  • upgrade_recommended: true
  • upgrade_reason

If shown, migrate to sqlite-vec (Node 22.13+) for better scale and latency.

localnest_index_project​

Builds or refreshes semantic index data.

Important parameters:

  • project_path
  • all_roots
  • force
  • max_files

Backends​

sqlite-vec

Preferred for larger repositories and stronger persistent indexing behavior.

json

Fallback backend for older or incompatible runtimes where sqlite-vec is unavailable.

1
Inspect index state

Use localnest_index_status to see whether the semantic index already exists and whether it is stale.

2
Index the smallest useful scope

Prefer project_path over all_roots for faster rebuilds and more focused retrieval.

3
Use hybrid search after indexing

Run localnest_search_hybrid once index data is ready and verify results with file reads.