NoteBrain CLI Skill für KI-Agenten
NoteBrain ist ein leistungsstarkes Go-CLI-Tool, das einen Obsidian-Notizgarten in eine lokale ChromaDB-Vektordatenbank indiziert. Es bietet semantische Suche, Graph-Traversierung, Rückwärtsverlinkungen, Entdeckung versteckter Beziehungen, vollständigen Notizenabruf und Tag-Analyse über Markdown-Notizen hinweg.
Grundlegende Ausführungsprinzipien & Begründung
Um effizient zu arbeiten und verschwendete Token oder hängende Sitzungen zu vermeiden, befolge diese Grundprinzipien:
- Nur NoteBrain – Keine generische Dateisuche: Verwende niemals
grep,find,lsoder Ad-hoc-Shell-Scripting gegen die Markdown-Dateien des Notizgartens, um die Frage des Benutzers zu beantworten. NoteBrain-Befehle sind speziell für die indizierte Vektor- und Graphdatenbank entwickelt und liefern stets qualitativ hochwertigere, relevantere Ergebnisse als eine Dateisystem-Textsuche. Behandlenotebrainals die einzige Schnittstelle zum Inhalt des Notizgartens. Wenn einnotebrain-Befehl scheinbar nichts Nützliches zurückgibt, verfeinere dienotebrain-Abfrage (andere Formulierung, breiterer--limit, alternativer Befehl), anstatt auf eine generische Dateisuche zurückzugreifen. - Nicht-interaktive Ausführung (
--format json): Standardmäßig startet NoteBrain ein interaktives Terminal-TUI (Bubble Tea), das für das menschliche Durchsuchen gedacht ist. Diese interaktive Oberfläche wird automatisierte Agentensitzungen aufhängen. Gib bei Abfragebefehlen immer--format json(oder--format ndjson/--format tsv) an, damit du strukturierte, analysierbare Daten sofort erhältst. Beachte, dass alle JSON-Envelope-Felder sauberesnake_case-Schlüssel verwenden (note_slug,title,file_path,score,tags,text). - KI-Agent-Befehlskette (
--jsonpath): Verwende--jsonpath(z. B.--jsonpath="$.results[0].note_slug"oder--jsonpath="$.results[*].note_slug"), wann immer du nur bestimmte Felder benötigst (z. B. zum Extrahieren von Notiz-Slugs oder Text, um sie in Folgebefehle weiterzuleiten). Wenn--jsonpathverwendet wird, werden Skalarwerte als rohe, unquotierte Zeichenketten ausgegeben und Arrays geben jedes Element in einer neuen Zeile aus, was eine nahtlose Shell-Variablenextraktion ohnejqermöglicht. - Vollständige Notizen abrufen (
notebrain get): Wenn diesearcheinen relevanten Notiz-Chunk zurückgibt, verwendenotebrain get <notiz-slug-oder-pfad>, anstatt zu raten, welcher Chunk-Index den vollständigen, rekonstruierten Markdown-Notizentext liefert, der aus allen indizierten Chunks zusammengesetzt wurde. Greife niemals aufcatfür die zugrunde liegende Notizgarten-Datei zurück –getrekonstruiert Chunk-Notizen korrekt und respektiert den indizierten Zustand des Notizgartens. - Inhalt für Synthese abrufen (
--include-text): Standardmäßig gebensearchund Traversierungsbefehle leichtgewichtige Metadaten-Envelopes zurück (Titel, Dateipfade, Tags, Ähnlichkeitswerte). Wenn deine Aufgabe das Zusammenfassen oder logische Schlussfolgern über einzelne Chunks direkt aus den Suchergebnissen erfordert, hänge--include-textan. Das zurückgegebenetext-Feld enthält reichhaltiges Markdown mit erhaltenen Codeblöcken, sodass Code-Snippets kopierbar sind. - Binär-Auflösung & Anführungszeichen: Führe in Entwicklungsumgebungen
./notebrainaus, wennnotebrainnicht im System-PATH ist. Notiztitel enthalten oft Leerzeichen oder Klammern ("Q3 Planning [Draft]"), kapsele daher Notiztitel, Tags und Suchanfragen immer in doppelte Anführungszeichen. - Eingebetteter persistenter Speicher: NoteBrain läuft ausschließlich als eingebettete Datenbank (
~/.notebrain/chroma). Es werden keine eigenständigen ChromaDB-Docker-Container oder HTTP-Server benötigt oder unterstützt. - Automatisierte Aufnahme: Die Aufnahme wird über OS-Scheduler (Cron/systemd-Timer alle 3 Stunden) durchgeführt. Du musst
ingestnicht manuell vor Abfragen ausführen, es sei denn, der Benutzer fordert ausdrücklich eine sofortige Neuindizierung nach dem Bearbeiten von Notizen an.
Befehlsauswahl-Leitfaden
Wähle den spezialisierten Befehl, der auf das Analyseziel des Benutzers zugeschnitten ist:
| Benutzerabsicht | Befehl | Warum & Wie zu verwenden |
|---|---|---|
| "Was sagen meine Notizen über X?" | search | Führt eine Vektor-Ähnlichkeitssuche über alle Notiz-Chunks durch. Verwende --tag="TagName", um nach Tag zu filtern. |
| "Lese den vollständigen Inhalt von Notiz Y" | get | Ruft den vollständigen Notiztext und die Metadaten per Slug oder Dateipfad ab und rekonstruiert sie. |
| "Was verlinkt direkt auf diese Notiz?" | backlinks | Findet explizite [[Wikilink]]-Verweise, die auf die Zielnotiz zeigen. |
| "Was ist strukturell im Graph benachbart?" | connections | Führt eine Breitensuche (BFS) über Wikilinks mit bis zu --hops N durch. Verwende --hops 1 oder --hops 2, um exponentielle Explosion zu vermeiden. |
| "Was ist bedeutungsverwandt, aber NICHT verlinkt?" | hidden | Deckt unverlinkte, aber semantisch ähnliche Notizen auf. Sehr wertvoll, um konzeptionelle Brücken zu entdecken. |
| "Finde Konzepte im Zusammenhang mit X, zentriert um Notiz Y" | boosted | Kombiniert Vektor-Ähnlichkeit mit Graph-Nähe zu einer --seed-Notiz. |
| "Welche Notizen teilen Tags mit X?" | tags | Analysiert Tag-Überlappungen. Gibt saubere Tag-Strings im tags-Array zurück. |
| "Ist die Datenbank aktuell?" | stats | Gibt Sammlungszahlen aus (chunks, links). Unterstützt --format=json und --jsonpath. |
| "Notizgarten indizieren oder neu indizieren" | ingest | Synchronisiert Markdown-Notizen in ChromaDB. Eine erneute Aufnahme ist idempotent. |
Befehlsyntax
Semantische Suche & Tag-Filterung (search)
notebrain search "kubernetes reconciliation" --tag="Kubernetes" --limit 5 --format json --include-text
Wichtige Such-Flags
| Flag | Zweck | Standard |
|---|---|---|
--top-k N | Maximale Anzahl von Chunks, die pro Notiz behalten werden. Verhindert, dass eine lange Notiz die Ergebnisse dominiert, während die Tiefe erhalten bleibt. | 3 |
--context-window N | Holt ±N benachbarte Chunks um jeden Treffer herum und füllt das context-Array. Verwende 1 oder 2 für die meisten Aufgaben. | 0 |
--has-tasks | Gib nur Chunks zurück, die Aufgabenlisten (Checkboxen) enthalten. | aus |
--has-code | Gib nur Chunks zurück, die eingerahmte Codeblöcke enthalten. | aus |
--section | Filtere die Ergebnisse auf Chunks unter einem bestimmten Überschriftspfad (z. B. "Architecture > Components"). | — |
--limit N | Maximale Gesamtzahl der zurückzugebenden Ergebnisse. | 10 |
--tag "TagName" | Nach Tag-Name filtern oder suchen. | — |
--min-score F | Unterdrücke Ergebnisse unterhalb dieses Ähnlichkeitswerts (0–1). | 0 |
Wann --context-window vs. notebrain get verwenden
- Verwende
--context-window 1, wenn du einen leichten umgebenden Kontext für mehrere Suchergebnisse auf einmal benötigst. Dies ist effizient – ein Suchaufruf liefert sowohl die übereinstimmenden Chunks als auch ihre Nachbarn, genug, um den lokalen Kontext zu verstehen, ohne ganze Notizen abzurufen. - Verwende
notebrain get, wenn du den vollständigen rekonstruierten Notiztext benötigst – zum Beispiel, wenn der Benutzer bittet, eine bestimmte Notiz zu lesen oder zusammenzufassen, oder wenn du die gesamte Dokumentstruktur sehen musst.
Der Window-Ansatz ist besonders wertvoll, wenn viele Suchergebnisse verarbeitet werden, da das Abrufen vollständiger Notizen für jedes Ergebnis verschwenderisch wäre. Hole zuerst das Fenster, dann rufe selektiv nur die Notizen mit get ab, die wirklich vollständigen Kontext benötigen.
Vollständigen Notizenabruf (get)
notebrain get "02areaskubernetesckadkubernetes-native-applications" --format json
Graph-Verbindungen & versteckte Links (connections, hidden)
notebrain connections "Distributed Systems" --hops 2 --format json
notebrain hidden "Microservices" --limit 5 --format json --include-text
JSON-Ausgabe-Schema
Das Verständnis der Ergebnisstruktur ist für eine zuverlässige Feldextraktion unerlässlich. Jeder Abfragebefehl verpackt die Ergebnisse in diesem Envelope:
{
"command": "search",
"query": "Semantic Search: \"kubernetes\"",
"total": 3,
"results": [
{
"note_slug": "02areaskubernetes-architecture",
"title": "Kubernetes Architecture",
"file_path": "02.Areas/Kubernetes/Architecture.md",
"score": 0.82,
"chunk_index": 2,
"tags": ["Kubernetes", "DevOps"],
"heading_path": "Components > Control Plane",
"text": "The API server validates and configures...",
"context": [
"Previous chunk text about etcd storage...",
"The API server validates and configures...",
"The scheduler watches for newly created Pods..."
]
}
]
}
| Feld | Vorhanden bei | Beschreibung |
|---|---|---|
note_slug | Immer | URL-sicherer Bezeichner, abgeleitet vom Dateipfad. |
title | Immer | Notiztitel aus Frontmatter oder Dateiname. |
file_path | Immer | Relativer Pfad innerhalb des Notizgartens. |
score | Immer | Ähnlichkeitswert (0–1) für die Suche; Sprunganzahl für Verbindungen. |
chunk_index | Suche, versteckt, boostiert | Welcher Chunk der Notiz übereinstimmte (0-basiert). |
tags | Wenn die Notiz Tags hat | Array von Tag-Strings. |
heading_path | Wenn der Chunk unter einer Überschrift ist | Breadcrumb-Pfad wie "Section > Subsection". |
text | Wenn --include-text übergeben wird | Der vollständige Markdown-Text des übereinstimmenden Chunks, mit erhaltenen Codeblöcken. |
context | Wenn --context-window N > 0 | Array von ±N benachbarten Chunk-Texten, geordnet nach Chunk-Index. |
extra | Verbindungen, Tags, boostiert | Befehlspezifische Informationen (z. B. "2 hop(s)", "graph-boosted"). |
Antwortqualität vertiefen: Multi-Signal-Abruf
Bevor du eine Frage wie „was weiß ich über X“ oder „fasse meine Notizen zu X zusammen“ beantwortest, bleib nicht bei einem einzigen search-Aufruf stehen. Suchergebnisse allein heben nur Chunks hervor, die semantisch nahe an der Abfrage sind – sie übersehen den umgebenden Kontext, den der Benutzer bewusst in seinen Graphen eingebaut hat. Erweitere das Bild immer:
- Suche mit Kontext – führe
searchmit--context-window 1 --include-text --top-k 2aus, um die relevantesten Chunks mit ihren umgebenden Absätzen zu erhalten. Dies liefert sowohl Präzision (den übereinstimmenden Chunk) als auch Kontext (was davor und danach kommt) in einem Aufruf. - Rückverlinkungen für jeden Startpunkt abrufen – führe
notebrain backlinks <start-slug> --format json --include-textaus, um jede Notiz zu extrahieren, die explizit auf den Startpunkt verlinkt. Diese Notizen hat der Benutzer manuell als verwandt kuratiert, daher ist ihr Inhalt fast immer signalstark und sollte in deiner Synthese stark gewichtet werden. - Verbindungen nach außen verfolgen – führe
notebrain connections <start-slug> --hops 2 --format jsonaus, um die lokale Graph-Nachbarschaft um den Startpunkt zu kartieren. Dies zeigt strukturell benachbarte Notizen (z. B. Notizen, die zwei Links entfernt sind), die möglicherweise nicht in einer reinen Vektorsuche auftauchen, aber Teil desselben Wissensclusters sind. - Nach versteckten Links suchen – führe
notebrain hidden <start-slug> --include-text --context-window 1aus, um konzeptionell verwandte Notizen zu erfassen, die der Benutzer noch nicht verlinkt hat. Weise den Benutzer explizit auf diese als potenziell fehlende Links in seinem Notizgarten hin, da dies einer der wertvollsten Unterscheidungsmerkmale von NoteBrain gegenüber einer einfachen Suche ist. - Synthetisieren, nicht nur auflisten – kombiniere die Startnotiz(en), ihre Rückverlinkungen, ihre
connections-Nachbarschaft und allehidden-Ergebnisse in einer einzigen kohärenten Antwort, wobei du unterscheidest, was explizit verlinkt ist (hohe Zuverlässigkeit) von dem, was nur semantisch ähnlich ist (einer Überprüfung wert).
Diese search → backlinks → connections → hidden-Kette sollte der Standard-Workflow für jede nicht-triviale explorative Frage sein, nicht nur ein einzelner search-Aufruf, da sie sowohl die explizite Struktur, die der Benutzer aufgebaut hat, als auch die implizite Struktur, die NoteBrain erkennen kann, an die Oberfläche bringt.
KI-Agenten-Befehlskette
# 1. Suche mit umgebendem Kontext – top-k hält die Ergebnisse vielfältig über Notizen hinweg
SLUG=$(notebrain search "message broker backpressure" --limit 3 --top-k 2 \
--context-window 1 --include-text --format json \
--jsonpath="$.results[0].note_slug")
# 2. Den vollständigen rekonstruierten Notiztext für den besten Treffer abrufen
notebrain get "$SLUG" --jsonpath="$.text"
# 3. Alle Rückverlinkungs-Slugs finden, die auf diese Notiz zeigen, mit ihrem Inhalt,
# um die Antwort in dem zu verankern, was der Benutzer explizit verlinkt hat
notebrain backlinks "$SLUG" --format json --include-text
# 4. Die Graph-Nachbarschaft durchlaufen, um strukturell benachbarte Notizen an die Oberfläche zu bringen,
# die die reine Vektorsuche übersehen würde
notebrain connections "$SLUG" --hops 2 --format json
# 5. Synthetisiere eine Antwort, die die Startnotiz, ihre Rückverlinkungen und verbundenen Notizen kombiniert
Sicherheitshinweise
- Alle notebrain-Operationen finden lokal in
~/.notebrain/chromastatt. Keine Daten verlassen den Rechner. - Die Aufnahme-Binärdatei wird über cron/systemd ausgeführt – stelle sicher, dass sie für den entsprechenden Benutzer ausführbar ist.
- Achte darauf, keine sensiblen Informationen (API-Schlüssel, Passwörter) in Notizen zu speichern, die indiziert werden, da sie über Abfragen abrufbar sind.