Lokale Wissensbasen

Eine lokale Wissensbasis ist ein gewöhnlicher Ordner mit Markdown-Dateien, die Sie in VelaTerm schreiben und organisieren. Notizen und Anhänge bleiben in diesem Ordner, sodass Sie sie auch mit anderen Editoren weiter bearbeiten können. Einige Menüeinträge bezeichnen eine lokale Wissensbasis als „Notizbuch“; beide Begriffe meinen denselben Ordner.

Neben Ihren lokalen Wissensbasen befindet sich die integrierte „Sitzungswissensdatenbank“. Sie enthält Wissen, das Agenten aus Ihren Sitzungen aufbereiten, und führt eigene Einträge, Quellen und einen eigenen Versionsverlauf; siehe Sitzungswissensdatenbank.

Die Wissensdatenbank öffnen

Klicken Sie im rechten Panel auf das Wissenssymbol (Kurzinfo „Wissensdatenbank“). In der Mitte öffnet sich der Tab „Wissensdatenbank“ mit der Startseite:

ein Suchfeld („Sitzungswissen und lokale Notizen durchsuchen…“, siehe den Abschnitt „Suchen“ weiter unten);
die „Sitzungswissensdatenbank“;
Ihre lokalen Wissensbasen („Lokale Wissensbasen“);
die Schaltflächen „Wissensbasis öffnen“ und „Wissensbasis erstellen“.

Das rechte Panel zeigt einen Baum mit drei Wurzeln: „Sitzungswissensdatenbank“, „Archivierte Sitzungen“ und „Lokale Wissensbasen“. Ein Klick auf einen Pfeil klappt einen Ordner direkt im Baum auf; mehrere Wissensbasen können gleichzeitig aufgeklappt sein. Ein Klick auf einen Ordnernamen zeigt seinen Inhalt, ein Klick auf eine Notiz öffnet sie. Der Link „Wissensbasen“ oben im Baum führt zur Startseite zurück, und die Schaltfläche „Eine Ebene nach oben“ im Seitenkopf wechselt zur übergeordneten Seite, ohne die Wissensdatenbank zu verlassen.

Notizen öffnen sich in normalen Dokument-Tabs und bieten dieselben Funktionen zum Bearbeiten, Speichern, Suchen und für den PDF-Export wie jede andere Markdown-Datei (siehe Dokumente und Browser-Tabs). Der Tab „Wissensdatenbank“ bleibt in der Tab-Leiste, damit Sie an die Stelle zurückkehren können, an der Sie waren.

Eine lokale Wissensbasis öffnen oder erstellen

Öffnen: Klicken Sie auf „Wissensbasis öffnen“ und wählen Sie einen Ordner. Die Desktop-App zeigt die Ordnerauswahl des Systems; ein Browser-Client zeigt eine Ordneransicht des verbundenen Computers. Einen vorhandenen Obsidian-Vault können Sie direkt öffnen: Die Dateien bleiben, wo sie sind, und versteckte Ordner wie .obsidian werden weder indiziert noch verändert.
Erstellen: Klicken Sie auf „Wissensbasis erstellen“, geben Sie unter „Name“ einen Namen ein, wählen Sie unter „Ordner“ einen Speicherort (oder klicken Sie auf „Durchsuchen“; vorgeschlagen wird ~/Notes) und bestätigen Sie. VelaTerm legt den Ordner an und öffnet ihn. Der übergeordnete Ordner muss vorhanden sein, und ein gleichnamiger Ordner darf nicht existieren; andernfalls zeigt VelaTerm „Das Ziel ist bereits vorhanden. Wählen Sie einen anderen Namen oder Ordner.“ an. Um einen vorhandenen Ordner zu verwenden, wählen Sie stattdessen „Wissensbasis öffnen“.
Umbenennen: Klicken Sie im Baum mit der rechten Maustaste auf eine Wissensbasis und wählen Sie „Umbenennen“. Dadurch wird der Ordner auf dem Datenträger umbenannt.
Schließen: Klicken Sie in der Symbolleiste der Wissensbasis auf „Notizbuch schließen“, oder wählen Sie den Befehl im Kontextmenü der Wissensbasis im Baum. Das Schließen entfernt den Ordner aus der Liste; seine Dateien bleiben auf dem Datenträger. Wenn Sie denselben Ordner erneut öffnen, sind sein Papierkorb und sein Importverlauf noch vorhanden.

„Lokal“ bezieht sich auf den Computer, auf dem das VelaTerm-Backend läuft, mit dem Sie verbunden sind. In einem Browser-Client durchsucht „Wissensbasis öffnen“ die Ordner dieses Computers, und beim Import werden die im Browser ausgewählten Dateien auf diesen Computer hochgeladen.

Dateien und Ordner importieren

Öffnen Sie die Ziel-Wissensbasis und klicken Sie in ihrer Symbolleiste auf „Importieren“.
Wählen Sie unter „Ordner“ das Ziel und dann „Dateien auswählen“ oder „Ordner auswählen“, oder ziehen Sie Dateien und Ordner in den Importbereich.
Prüfen Sie die Liste und bestätigen Sie.

Der Import läuft im Hintergrund, sodass Sie während des Kopierens die Seite wechseln oder Notizen öffnen können. Sein Fortschritt erscheint in der Symbolleiste der Wissensbasis und auf der Startseite, und er lässt sich im Importdialog oder unter „Importverlauf“ abbrechen. Nach Abschluss zeigt ein Banner die Anzahl der importierten und übersprungenen Dateien; ist das Fenster nicht im Fokus, erscheint eine Systembenachrichtigung („Import abgeschlossen“ oder „Import fehlgeschlagen“). In einer Wissensbasis kann jeweils nur ein Import laufen.

Ein Import kopiert Dateien unverändert, einschließlich Dateinamen mit Nicht-ASCII-Zeichen, der relativen Ordnerstruktur und der Anhänge, und verändert die Originale nie. Beim Import eines Ordners wird der Ordner selbst mit übernommen. Würde eine Datei eine vorhandene überschreiben, wird der gesamte Stapel abgelehnt. Versteckte Dateien und versteckte Konfigurationsordner werden übersprungen. Die Dateiauswahl im Browser liefert keine leeren Ordner, daher werden leere Ordner nicht importiert.

Ein Import kann bis zu 5.000 Dateien (übersprungene versteckte Dateien zählen mit) und insgesamt bis zu 1 GiB umfassen, bei höchstens 100 MiB pro Datei. Die Dateien werden zunächst zwischengespeichert und erscheinen erst im Ziel, wenn der gesamte Stapel angekommen ist; ein abgebrochener Upload taucht daher nie als halb geschriebene Notiz auf.

„Importverlauf“ listet jeden Import mit Zeitpunkt, Ziel („Stammverzeichnis der Wissensbasis“ für den obersten Ordner), Status („Wird importiert“, „Abgeschlossen“, „Fehlgeschlagen“, „Abgebrochen“ oder „Unterbrochen“), der Anzahl importierter und übersprungener Dateien, der Größe und der Dauer auf. Klicken Sie auf „Dateien (N)“, um jede Datei und den Grund für ein Überspringen zu sehen. „Eintrag löschen“ entfernt den Eintrag aus dem Verlauf; die importierten Dateien bleiben erhalten. Ein Import, dessen Fortschritt seit mehr als zwei Minuten stillsteht, etwa weil die App unerwartet beendet wurde, wird als „Unterbrochen“ markiert; das Löschen seines Eintrags entfernt auch die dafür zwischengespeicherten Dateien.

Notizen schreiben und organisieren

Die Seite einer Wissensbasis bietet die Ansichten „Letzte Notizen“, „Papierkorb“ und „Importverlauf“, eine Schaltfläche „Neue Notiz“ sowie in der Symbolleiste die Schaltflächen „Neuer Ordner“, „Importieren“ und „Notizbuch schließen“. Die Notizliste lässt sich nach Tag filtern („Alle Tags“) und nach „Zuletzt aktualisiert“ oder „Titel“ sortieren.

Solange die Seite einer Wissensbasis angezeigt wird, erstellt ⌘N / Ctrl+N eine „Neue Notiz“, ⌘O / Ctrl+O öffnet „Schnell öffnen“ (eine Notiz über ihren Pfad finden), und ⌘⇧F / Ctrl+Shift+F setzt den Fokus in das Feld „Notizen durchsuchen…“.
Um eine Notiz umzubenennen, klicken Sie sie im Baum mit der rechten Maustaste an und wählen Sie „Umbenennen“. Zum Verschieben ziehen Sie sie auf einen anderen Ordner derselben Wissensbasis. „Löschen“ verschiebt sie in den Papierkorb der Wissensbasis.
Bei einem geöffneten Ordner verschiebt „Umbenennen oder verschieben“ den Ordner an einen Pfad relativ zum Stammverzeichnis der Wissensbasis; der übergeordnete Ordner muss bereits vorhanden sein. Wird eine Notiz oder ein Ordner verschoben, werden Links in anderen Notizen derselben Wissensbasis angepasst; der Linktext bleibt erhalten, und Code bleibt unberührt.
Gelöschte Elemente landen in einem Ordner .vkb-trash innerhalb der Wissensbasis. Öffnen Sie „Papierkorb“ und klicken Sie auf „Wiederherstellen“, um ein Element zurückzuholen; eine vorhandene Datei mit demselben Namen wird nie überschrieben.
Tags stammen aus #tag im Text und aus einer YAML-Liste bzw. einem YAML-Array tags.
In eine Notiz eingefügte Bilder werden in einem Ordner assets neben der Notiz gespeichert.

Baum und Listen werden etwa alle fünf Sekunden aktualisiert, solange die Seite sichtbar ist, und außerdem, wenn das Fenster wieder den Fokus erhält. Ein geöffneter Dokument-Tab erkennt Änderungen durch andere Programme und bietet an, die Datei neu zu laden.

Seiten und Dialoge der Wissensbasen, der Importverlauf, Suchen, Suchbereich, Tags, Sortierung und „Schnell öffnen“ haben jeweils eigene URLs, sodass Sie die Seite neu laden oder die Vor- und Zurück-Schaltflächen des Browsers verwenden können. Nicht gespeicherter Text und Formulareingaben sind nicht Teil der URL.

Suchen

Startseite: durchsucht die Sitzungswissensdatenbank und alle lokalen Wissensbasen gleichzeitig und gruppiert die Ergebnisse nach Quelle. Archivierte Sitzungen sind nicht enthalten.
Rechtes Panel: „Notizen durchsuchen…“ über dem Baum durchsucht alle lokalen Wissensbasen.
Seite einer Wissensbasis: „Notizen durchsuchen…“ durchsucht Notiznamen, Pfade und Text. „Suchbereich“ wechselt zwischen „Diese Wissensbasis“ und „Alle Wissensbasen“.

Bei mehreren Suchwörtern müssen alle vorkommen. Jedes Ergebnis zeigt seine Wissensbasis oder Sitzungsgruppe, einen Textausschnitt, die Zeilennummer, die Anzahl der Treffer und unter „Verknüpfte Notizen“ die Notizen, auf die die gefundene Notiz verlinkt; ein Klick auf einen dieser Einträge öffnet ihn. Mit ↑ und ↓ wählen Sie ein Ergebnis aus, mit Enter öffnen Sie es, und mit Esc leeren Sie die Suche. Die Ergebnisse sind zuerst nach Treffern im Namen oder Pfad, dann nach der Anzahl der Treffer und schließlich nach der letzten Aktualisierung sortiert. Es werden bis zu 100 Ergebnisse aufgelistet; gibt es mehr, endet die Liste mit „Es werden nur die ersten Ergebnisse aufgelistet. Grenzen Sie die Suche ein, um die übrigen zu sehen.“

VelaTerm sucht zuerst nach exakten Treffern und greift nur dann auf ungefähre Treffer zurück, wenn es keine gibt; in diesem Fall erscheint „Keine genauen Treffer. Es werden ungefähre Ergebnisse angezeigt.“ Die ungefähre Suche gilt für Wörter aus lateinischen Buchstaben und Ziffern: Buchstaben in der richtigen Reihenfolge (knwl findet knowledge), Anfangsbuchstaben (kb findet knowledge base) und kleine Tippfehler (ein Fehler bei Wörtern ab vier Zeichen, zwei ab acht Zeichen; knoledge findet knowledge). Chinesischer und anderer nicht lateinischer Text wird exakt abgeglichen.

Links und Kompatibilität mit vorhandenen Dateien

VelaTerm erkennt die gängigen Formen [[note]], [[folder/note|label]] und [[note#heading]], relative Standard-Markdown-Links sowie ![[image.png]]. Es nutzt sie, um Links beim Verschieben von Notizen anzupassen, um „Verknüpfte Notizen“ in Suchergebnissen aufzulisten und für die unten beschriebenen vkb-Befehle. Im Editor werden [[…]]-Links als normaler Text angezeigt. Tragen mehrere Dateien denselben Namen, wird ein kurzer Link nur aufgelöst, wenn das Ziel eindeutig ist; andernfalls geben Sie den Ordnerpfad mit an.

Dateien bleiben reines Markdown, und YAML-Front-Matter bleibt in der Datei; der Modus „Quelltext“ im Editor zeigt sie unverändert an. Markdown-Dateien, die nicht in UTF-8 vorliegen oder größer als 5 MiB sind, werden nicht als Notizen aufgeführt und unter „Übersprungen“ gezählt. Eine Wissensbasis kann bis zu 50.000 Dateien und Ordner enthalten; ein größerer Ordner lässt sich nicht öffnen und zeigt „Die Datei oder Auswahl überschreitet die Grenzen des Notizbuchs.“ an. Symbolischen Links wird nicht gefolgt.

Diese Funktionen decken die alltägliche Arbeit mit lokalen Dateien, Ordnern, Markdown, Links und Suche ab. Obsidian-Plugins, Designs, Canvas, Blockreferenzen, eingebettete Notizen und YAML-Aliasse werden nicht unterstützt; die entsprechenden Dateien bleiben unverändert. Zum Dateimodell und zur Linksyntax siehe die Obsidian-Dokumentation zu Vaults, internen Links und Anhängen.

Aus der Sitzungswissensdatenbank kopieren und Abfragen durch Agenten

Öffnen Sie einen Eintrag in der Sitzungswissensdatenbank, wählen Sie „In ein lokales Notizbuch kopieren“ und legen Sie dann die Ziel-Wissensbasis und den Dateinamen fest. Die Kopie ist eine eigenständige Markdown-Notiz; der ursprüngliche Eintrag, seine gespeicherten Quellstände und sein Versionsverlauf bleiben, wo sie sind.

In einer VelaTerm-Sitzung können Sie oder ein Agent registrierte lokale Wissensbasen mit vkb lesen:

vkb notes "reading notes"
vkb note <knowledge-base-ID> "reading/how-to-take-notes.md"
vkb search "architecture decision"

notes durchsucht jede lokale Wissensbasis, die im aktuellen Backend registriert ist. Jedes Ergebnis enthält vaultId, vaultName, path, absolutePath, line, matches, score, matched (der tatsächlich gefundene Text), related (Notizen, auf die diese Notiz verlinkt) und summary (der Text rund um den Treffer). Die Antwort meldet außerdem total, hasMore, unavailable (Wissensbasen, die nicht gelesen werden konnten) und fuzzy (ob die Ergebnisse ungefähr sind). Es werden bis zu 100 Ergebnisse zurückgegeben.
note liefert Text, Gliederung, Links, Rückverweise und Tags einer Notiz.
search liefert Treffer aus der Sitzungswissensdatenbank, aus lokalen Notizen und, sofern ein Code-Index vorhanden ist, aus dem Codegraph (siehe Codegraph und Wissensdatenbank).

Diese Befehle lesen nur. Sie verändern nie Notizen, und VelaTerm fügt Inhalte der Wissensbasen nicht automatisch zu Sitzungen hinzu.

Speicherung und Protokolle

Die Dateien auf dem Datenträger sind die maßgebliche Fassung Ihrer Notizen und Anhänge. Die Anwendungsdatenbank (Tabellen kb_*) speichert nur die Liste der registrierten Wissensbasen, Papierkorbeinträge, den Importverlauf und einen Suchcache, der sich neu aufbauen lässt. Die Sitzungswissensdatenbank verwendet eigene Tabellen memory_*.

Öffnen, Schreiben, Verschieben, Löschen, Wiederherstellen und Importieren werden im Laufzeitprotokoll mit einer Vorgangs-ID, Mengenangaben und der benötigten Zeit erfasst, nie mit Notizinhalten. Diese Zeilen verwenden das Ereignis knowledge; ist VLX_LOG_DIR nicht gesetzt, legt VLX_KNOWLEDGE_LOG_DIR ihr Verzeichnis fest. Der Importverlauf wird in der Datenbank gespeichert und auf der Seite „Importverlauf“ angezeigt. Um eine Wissensbasis vollständig zu sichern, bewahren Sie sowohl ihren Ordner als auch die Anwendungsdaten auf, die ihre Papierkorb- und Importeinträge enthalten.