vhecfsck — Vector Index Audit & Diagnostics

Read-only, empirical, offline auditor for vector indexes that detects silent recall decay and index pathologies before they reach production.

The name is a personalized play on Unix fsck: a vector-index checker, with an H from the author's name, Hector. Identifiers stay lowercase vhecfsck.

Quickstart

Run the interactive CLI demonstration from any machine with Python ≥ 3.11:

uvx vhecfsck demo

Or install via pip:

pip install vhecfsck

Current release: 0.1.3 · PyPI. On GitHub Pages the changelog is /changelog (no trailing slash). /changelog/ 404s, same as /releasing/ versus /releasing.

---

Core Principles

1. Strictly Read-Only: vhecfsck never executes writes, VACUUM, REINDEX, or state mutations.
2. Empirical Measurements: All diagnostic scores derive from exact k-NN ground truth computations.
3. Zero Network Egress: Air-gapped, zero telemetry, zero analytics, zero external script requests.
4. Honest Capabilities: Unsupported engine features report UNAVAILABLE (exit code 3) rather than fake healthy scores.

---

Documentation Overview

• Concepts & Pathologies: Deep dive into silent recall decay, hubness, tombstone accumulation, and centroid drift.
• Metrics Reference: Normative specifications and formulas derived from 02-metrics-spec.md.
• Engine Guides: Setup and introspection guides for LanceDB, Qdrant, and pgvector.
• CI Integration: Copy-pasteable recipes for GitHub Actions, GitLab CI, Kubernetes, and Prometheus.
• Read-Only Guarantee: Technical verification details and security invariants.
• Calibration & Thresholds: Empirical threshold calibration across dimensions $d \in [64, 1536]$.
• Performance Budgets: Hardware guidance and scaling benchmarks up to 1,000,000 vectors.
• CLI Reference: Programmatically generated Typer CLI reference.
• Report Schema Reference: Programmatically generated Pydantic v1.1 JSON schema reference.