vector drift

vector drift listet jede Entität, die im Graph-Index existiert, aber im Vektor-Index entweder fehlt oder veraltet ist. „Veraltet" heißt: die persistierten content_hash-Werte stimmen nicht mehr mit dem überein, was der Chunker für die aktuelle Datei produzieren würde — die Datei wurde geändert, das Embedding hat den Sprung nicht mitgemacht. Reine Lese-Operation; weder Graph noch Vektor-Index werden angefasst.

Wofür ist das?

Backlog des Embedding-Workers sehen. Solange der Worker läuft und Ollama erreichbar ist, schmilzt die Liste mit jedem verarbeiteten Job. Steht sie still, ist der Worker abgewürgt oder Ollama unerreichbar — Diagnose dann über vector ping und die Worker-Logs.
Nach einem vector rebuild --force Fortschritt prüfen. Der Force-Rebuild leert den Index und stellt jede Entität als RefreshEmbeddingJob in die Queue. vector drift zeigt, wie viele davon noch offen sind.
Watcher-Aussetzer aufdecken. Wenn der Watcher off war, während Dateien geändert wurden, sind die Embeddings nun veraltet. Ohne den Stale-Pfad würde dieser Befund unsichtbar bleiben, bis der nächste vector rebuild ihn aufräumt.
Monitor-fähiger Indikator. Der Exit-Code unterscheidet zwischen „alles in Sync" (0) und „mindestens eine Entität fehlt oder ist veraltet" (2) — ein Skript kann darauf reagieren, ohne die Ausgabe zu parsen.

Aufruf

apparat vector drift --vault=recherche
apparat vector drift --vault=recherche --all
apparat vector drift --vault=recherche --no-stale     # nur fehlende, kein Inhalts-Scan

Option	Bedeutung
`--vault=<name	path
`--all`	Druckt jede gemeldete Entität pro Kategorie, statt der ersten 25. Sinnvoll bei großen Backlogs für Skripte oder Logs.
`--no-stale`	Überspringt den Inhalts-Drift-Scan (Chunker-Re-Pass) und meldet nur Entitäten, die ganz fehlen. Schneller bei großen Vaults — vor allem dann hilfreich, wenn der Watcher nachweislich gesund war.

Was kostet der Stale-Scan?

Stale-Detection läuft den Chunker einmal pro indizierter Entität an und vergleicht die Hashes gegen die persistierten Werte. Keine Ollama-Aufrufe — der Scan ist rein CPU/Disk. Auf einem 1000-Entity-Vault sind das wenige Sekunden, auf einem 10k-Vault einige Zehner-Sekunden. Wer den Scan in einem Skript häufig laufen lässt und auf Geschwindigkeit drückt, nutzt --no-stale; für die normale Diagnose ist der Default-Pfad richtig.

Beispielausgabe

Mit Drift in beiden Kategorien:

Vault "recherche" — vector index drift:

  Missing (no chunks in the index):
    WWaWQ2ze  Tollwerk GmbH
    V1StGXRa  Maria Beispiel

  Stale (persisted chunks no longer match the file body):
    Qw9pLm2n  Beispiel-Organisation

(2 missing, 1 stale, of 1000 entities total.)

Mit vielen fehlenden, ohne --all:

Vault "recherche" — vector index drift:

  Missing (no chunks in the index):
    abc12345  Erste Entität
    def67890  Zweite Entität
    …
    … 117 more (use --all to list every entity).

(142 missing, 0 stale, of 1000 entities total.)

Index vollständig und aktuell:

✅ Vault "recherche" — vector index in sync (1000 entities, all embedded and current).

Exit-Codes

Code	Bedeutung
0	Jede Entität hat mindestens einen Chunk im Index, und alle Hashes stimmen mit der Datei überein — keine Drift.
1	Vault konnte nicht aufgelöst werden, oder die Vektor-Datenbank ist nicht öffenbar (z. B. fehlende `sqlite-vec`-Extension auf dem Host).
2	Mindestens eine Entität fehlt im Index oder ist veraltet. Die Liste in der Ausgabe nennt sie nach Kategorie.