mindnet/docs/Handbuch.md

📘 Mindnet Skript-Handbuch

Dieses Handbuch dokumentiert die implementierten Skripte für das Projekt mindnet Wissensnetzwerk.
Es beschreibt Zweck, Parameter und typische Aufrufe. Alle Beispiele sind geprüft und lauffähig.

Alle Skripte liegen in ~/mindnet/scripts/.
Ausführung erfolgt im aktivierten venv:

cd ~/mindnet
source .venv/bin/activate

---

1. Vault anlegen (für Tests)

make_test_vault.py

Zweck:
Erstellt einen kleinen, nachvollziehbaren Test-Vault mit Markdown-Dateien.
Szenarien: offene Links, nachträgliche Anlage fehlender Notes, geänderte Chunk-Grenzen.

Parameter:

• --out PATH : Zielverzeichnis (Default: ./test_vault)
• --force : Existierenden Ordner löschen und neu anlegen
• --with-missing : Optional – auch die missing-note gleich anlegen

Hinweise für Tests

1. Erster Import (dry-run oder --apply): Es gibt einen „leeren“ Link missing-note.
2. Lege danach eine Datei für „missing-note“ an (mit gleicher ID im YAML) und importiere erneut: -> Erwartung: Edges für ehemals leeren Link werden korrekt nachgezogen (references + backlink).
3. Ändere den Body von exp-one.md so, dass andere Chunk-Grenzen entstehen und importiere erneut: -> Erwartung: Chunks/Edges/Note werden für betroffene Noten aktualisiert.

Kompatibel mit:

• note.schema.json: 'created'/'updated' müssen strings sein. (Wichtig!)

Beispiele:

python3 -m scripts.make_test_vault --out ./test_vault --force
python3 -m scripts.make_test_vault --out ./test_vault --force --with-missing

---

2. Import in Qdrant

import_markdown.py

Zweck:
Importiert Notes/Chunks/Edges aus einem Vault nach Qdrant.

• prüft Frontmatter
• chunked Inhalte + Embeddings
• erzeugt Edges (references, references_at, backlink)
• erkennt geänderte Dateien automatisch
• optional: Purge der alten Chunks/Edges pro Note

Parameter:

• --vault PATH : (Pflicht) Vault-Verzeichnis
• --apply : Änderungen wirklich durchführen (sonst Dry-Run)
• --purge-before-upsert : Vor Upsert alte Chunks/Edges nur der geänderten Notes löschen
• --note-id ID : Nur eine bestimmte Note importieren

Beispiele:

python3 -m scripts.import_markdown --vault ./vault
python3 -m scripts.import_markdown --vault ./vault --apply
python3 -m scripts.import_markdown --vault ./vault --apply --purge-before-upsert

---

3. Konsistenzprüfungen

audit_vault_vs_qdrant.py

Zweck:
Vergleicht Vault-Inhalte mit Qdrant.

• Zählt Notes/Chunks/Edges
• Verifiziert Anzahl Wikilinks vs. Edges
• Meldet Mismatches pro Note

Parameter:

• --vault PATH : Vault-Verzeichnis
• --prefix STR : Prefix für Qdrant-Collections (Default: mindnet)

Beispiel:

python3 -m scripts.audit_vault_vs_qdrant --vault ./vault --prefix mindnet

---

validate_edges.py

Zweck:
Prüft die Edges-Collection in Qdrant.

• Zählt Edges pro Typ
• Kontrolliert Invarianten (z. B. jede Reference hat Backlink)
• Listet unresolved Edges auf

Parameter:

• --prefix STR : Prefix für Qdrant-Collections
• --details : Detailausgabe mit Beispielen

Beispiel:

python3 -m scripts.validate_edges --prefix mindnet --details

---

4. Qdrant zurücksetzen

reset_qdrant.py

Zweck:
Setzt die Qdrant-Collections zurück.

• „wipe“: löscht Collections komplett (inkl. Schema)
• „truncate“: löscht nur Inhalte, behält Collections

Parameter:

• --mode {wipe,truncate} : Aktion
• --prefix STR : Prefix der Collections (Default: mindnet)
• --yes : Automatische Bestätigung
• --dry-run : Nur anzeigen, nicht ausführen

Beispiele:

python3 -m scripts.reset_qdrant --mode truncate --prefix mindnet --yes
python3 -m scripts.reset_qdrant --mode wipe --prefix mindnet --yes

---

5. Diagnose

diagnose_changed.py

Zweck:
Prüft, ob die Datei-Hashes (sha256) mit den gespeicherten hash_fulltext in Qdrant übereinstimmen.
Hilft, wenn der Importer zu viele Dateien als „changed“ erkennt.

Parameter:

• --vault PATH : Vault-Verzeichnis
• --prefix STR : Prefix (Default: mindnet)
• --note-id ID : Nur bestimmte Note prüfen
• --all : Alle Notes prüfen

Beispiel:

python3 -m scripts.diagnose_changed --vault ./vault --prefix mindnet --all

---

6. Unresolved Links nachträglich auflösen

resolve_unresolved_references.py

Zweck:
Prüft offene Wikilinks (status=unresolved) und fügt Edges nach, wenn inzwischen passende Notizen existieren.

Parameter:

• --prefix STR : Prefix für Qdrant-Collections
• --apply : Änderungen wirklich ausführen (sonst nur Vorschau)

Beispiele:

python3 -m scripts.resolve_unresolved_references --prefix mindnet
python3 -m scripts.resolve_unresolved_references --prefix mindnet --apply

---

✅ Typische Workflows

A) Vault neu importieren

python3 -m scripts.reset_qdrant --mode truncate --prefix mindnet --yes
python3 -m scripts.import_markdown --vault ./vault --apply
python3 -m scripts.audit_vault_vs_qdrant --vault ./vault --prefix mindnet

B) Änderungen einspielen (mit Purge für geänderte Notes)

python3 -m scripts.import_markdown --vault ./vault --apply --purge-before-upsert
python3 -m scripts.audit_vault_vs_qdrant --vault ./vault --prefix mindnet

C) Unresolved Links nachziehen

python3 -m scripts.resolve_unresolved_references --prefix mindnet --apply
python3 -m scripts.validate_edges --prefix mindnet --details

D) Test-Vault Szenario durchspielen

python3 -m scripts.make_test_vault --out ./test_vault --force
python3 -m scripts.import_markdown --vault ./test_vault --apply
python3 -m scripts.audit_vault_vs_qdrant --vault ./test_vault --prefix mindnet