claude-regelwerk/.vault-tools/obsidian-vault-navigator/references/indexing.md

Die Referenzschicht

Warum überhaupt ein Index

Ein Agent, der eine Frage an einen Vault mit 500 Notizen stellt, hat drei Möglichkeiten: alles lesen (sprengt den Kontext), grep (findet Wortformen, aber nicht Bedeutung, und liefert Treffer ohne Einordnung), oder eine Zwischenschicht, die pro Notiz genau so viel weiß, dass sich entscheiden lässt, ob man sie aufmacht. Die dritte Variante ist der Index.

Größenordnung: 500 Notizen à 800 Wörter sind rund 500.000 Token. Der Index derselben 500 Notizen liegt bei etwa 25.000 Token — und eine typische Abfrage gibt davon 10–40 Zeilen aus, also ein paar hundert Token. Deshalb: nie den Index komplett lesen, immer vault_query.py fragen.

Erzeugte Dateien

_index/vault-index.json

Kompaktes JSON ohne Einrückung, Kurzschlüssel zur Platzersparnis:

Schlüssel	Bedeutung
p	Pfad relativ zum Vault
u	uid
t	type
s	status
n	Titel
m	summary
g	tags
r	Projekt-Slug
c / d	created / updated
h	Überschriften (max. 12)
l	ausgehende Links
w	Wortzahl (bei Assets: Dateigröße)

Leere Felder fehlen ganz. Der meta-Block enthält Zählungen, Typverteilung, Statusverteilung, Top-Tags und die Zahl toter Links.

Das Feld h ist der zweite Hebel nach m: Bei einer langen Notiz zeigen die Überschriften, welcher Abschnitt gebraucht wird — statt 3.000 Wörter zu lesen, liest man 300.

_index/INDEX.md

Menschenlesbare Übersicht, nach Typ gruppiert, jede Zeile ein Wikilink plus Zusammenfassung. In Obsidian direkt navigierbar. Bei über 200 Notizen enthält die Datei selbst den Hinweis, sie nicht komplett zu lesen.

_index/backlinks.json

{ "pfad/zur/notiz.md": ["pfad/quelle1.md", …] }. Basis für --links-to und die Waisen-Erkennung.

Wann neu bauen

• nach dem Anlegen, Verschieben, Umbenennen oder Löschen von Notizen
• nach Frontmatter-Änderungen
• vor einer Arbeitssitzung, wenn zwischendurch in Obsidian gearbeitet wurde

vault_query.py vergleicht die Änderungszeiten und warnt auf stderr, wenn Notizen neuer sind als der Index. Der Lauf über einige tausend Dateien dauert Sekunden, also im Zweifel neu bauen.

Automatisieren geht per Git-Hook (.git/hooks/pre-commit) oder Cron:

python3 .claude/skills/obsidian-vault-navigator/scripts/build_index.py --vault . --quiet

Abfrage-Rezepte

Q=".claude/skills/obsidian-vault-navigator/scripts/vault_query.py"

# Womit habe ich mich zu Thema X beschäftigt?
python3 $Q --text x

# Laufende Code-Projekte, als fertige Wikilink-Liste für eine Antwort
python3 $Q --type project-code --status active --format md

# Alles zu einem Projekt, inklusive Unternotizen und Anhängen
python3 $Q --project auth-service

# Passendes Template-Projekt finden, ohne eines zu öffnen
python3 $Q --type template-project

# Was hat sich diese Woche getan?
python3 $Q --since 7 --sort updated

# Kandidaten fürs Archiv
python3 $Q --status active --stale 180

# Wer verweist auf diese Notiz?
python3 $Q --links-to 30_Research/rate-limiting.md

# Pflegeliste: Notizen ohne summary
python3 $Q --no-summary --limit 100 --format paths

# Struktur einer langen Notiz sehen, bevor man sie liest
python3 $Q --text "kubernetes netzwerk" --format headings

Mehrere --text werden UND-verknüpft, mehrere --type/--tag/--status ODER-verknüpft (bei --tag müssen alle angegebenen Tags vorhanden sein).

Wenn der Index nichts findet

1. Filter lockern — oft ist --type zu eng gesetzt.
2. Anderes Wort probieren; der Index kennt nur Titel, Summary, Tags, Überschriften und Pfad, keinen Fließtext.
3. Erst dann Volltext: grep -ril "begriff" --include="*.md" .
4. Findet grep etwas, das der Index nicht hatte, ist das ein Befund: Der Notiz fehlt ein Tag oder eine bessere summary. Gleich nachziehen — der Index wird dadurch mit jedem Miss besser.

Grenzen

Der Index ist Metadaten, keine Semantik. Er findet nichts, was nirgends benannt ist, und er versteht keine Synonyme. Für semantische Suche im großen Vault gibt es lokale Werkzeuge (z. B. Obsidians eigene Suche mit Operatoren oder externe Embedding-Indizes) — die ersetzen diese Schicht nicht, sondern ergänzen sie: Der Index bleibt die billige erste Stufe.

Verhältnis zu Obsidian Bases

Obsidian Bases (.base-Dateien) erzeugen Tabellen- und Kartenansichten aus Properties — dieselben Felder, die auch der Index nutzt. Wer im Obsidian-UI dieselben Übersichten will, legt Bases an; für den Agenten bleibt der JSON-Index der billigere Weg. Für die korrekte .base-Syntax den offiziellen Skill obsidian-bases verwenden.