Communitygithub.com

nmdra/notebrain-cli

NoteBrain ist ein leistungsstarkes Go-CLI-Tool, das deinen Obsidian-Notizgarten in eine lokale ChromaDB-Vektordatenbank indiziert. So können KI-Agenten dein persönliches Wissensarchiv intelligent durchsuchen, semantische Ähnlichkeiten finden und Verbindungen zwischen Notizen aufdecken.

Was ist notebrain-cli?

NoteBrain ist ein spezialisiertes CLI-Tool für KI-Agenten (z. B. Claude Code, Cursor, Codex), das entwickelt wurde, um einen Obsidian-Notizgarten in eine lokale ChromaDB-Vektordatenbank zu indizieren. Es ermöglicht Agenten, semantische Suchen, Graph-Traversierung, Rückwärtsverlinkungen, versteckte Beziehungen und Tag-Analysen durchzuführen. Die Skill-Beschreibung legt großen Wert auf Effizienz: Agenten sollen immer `notebrain` anstelle von generischen Dateisuchtools wie `grep` oder `find` verwenden, um qualitativ hochwertigere Ergebnisse zu erzielen und Token zu sparen. Wichtig ist die Verwendung des `--format json`-Flags, um die interaktive TUI zu vermeiden, die Sessions hängen lassen könnte. Die Befehle sind spezifisch: `search` für semantische Ähnlichkeit, `get` für vollständige Notizen, `backlinks` für explizite Verweise, `connections` für Graph-Nachbarschaft, `hidden` für unverlinkte semantische Ähnlichkeiten, `boosted` für eine Kombination aus beidem, `tags` für Tag-Analyse, `stats` für Datenbankinformationen und `ingest` für die Indizierung. Der Skill fördert eine mehrstufige Abrufstrategie: Zuerst `search` mit `--context-window`, dann `backlinks`, `connections` und `hidden`, um sowohl die explizite als auch die implizite Wissensstruktur zu erfassen.

Funktioniert mit~Claude Code~Codex CLI~Cursor
npx skills add nmdra/notebrain-cli

In Ihrer bevorzugten KI fragen

Öffnet einen neuen Chat, in dem dieser Agent-Skill bereits geladen ist.

Dokumentation

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:

  1. Nur NoteBrain – Keine generische Dateisuche: Verwende niemals grep, find, ls oder 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. Behandle notebrain als die einzige Schnittstelle zum Inhalt des Notizgartens. Wenn ein notebrain-Befehl scheinbar nichts Nützliches zurückgibt, verfeinere die notebrain-Abfrage (andere Formulierung, breiterer --limit, alternativer Befehl), anstatt auf eine generische Dateisuche zurückzugreifen.
  2. 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 saubere snake_case-Schlüssel verwenden (note_slug, title, file_path, score, tags, text).
  3. 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 --jsonpath verwendet wird, werden Skalarwerte als rohe, unquotierte Zeichenketten ausgegeben und Arrays geben jedes Element in einer neuen Zeile aus, was eine nahtlose Shell-Variablenextraktion ohne jq ermöglicht.
  4. Vollständige Notizen abrufen (notebrain get): Wenn die search einen relevanten Notiz-Chunk zurückgibt, verwende notebrain 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 auf cat für die zugrunde liegende Notizgarten-Datei zurück – get rekonstruiert Chunk-Notizen korrekt und respektiert den indizierten Zustand des Notizgartens.
  5. Inhalt für Synthese abrufen (--include-text): Standardmäßig geben search und 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-text an. Das zurückgegebene text-Feld enthält reichhaltiges Markdown mit erhaltenen Codeblöcken, sodass Code-Snippets kopierbar sind.
  6. Binär-Auflösung & Anführungszeichen: Führe in Entwicklungsumgebungen ./notebrain aus, wenn notebrain nicht im System-PATH ist. Notiztitel enthalten oft Leerzeichen oder Klammern ("Q3 Planning [Draft]"), kapsele daher Notiztitel, Tags und Suchanfragen immer in doppelte Anführungszeichen.
  7. 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.
  8. Automatisierte Aufnahme: Die Aufnahme wird über OS-Scheduler (Cron/systemd-Timer alle 3 Stunden) durchgeführt. Du musst ingest nicht 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:

BenutzerabsichtBefehlWarum & Wie zu verwenden
"Was sagen meine Notizen über X?"searchFü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"getRuft den vollständigen Notiztext und die Metadaten per Slug oder Dateipfad ab und rekonstruiert sie.
"Was verlinkt direkt auf diese Notiz?"backlinksFindet explizite [[Wikilink]]-Verweise, die auf die Zielnotiz zeigen.
"Was ist strukturell im Graph benachbart?"connectionsFü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?"hiddenDeckt unverlinkte, aber semantisch ähnliche Notizen auf. Sehr wertvoll, um konzeptionelle Brücken zu entdecken.
"Finde Konzepte im Zusammenhang mit X, zentriert um Notiz Y"boostedKombiniert Vektor-Ähnlichkeit mit Graph-Nähe zu einer --seed-Notiz.
"Welche Notizen teilen Tags mit X?"tagsAnalysiert Tag-Überlappungen. Gibt saubere Tag-Strings im tags-Array zurück.
"Ist die Datenbank aktuell?"statsGibt Sammlungszahlen aus (chunks, links). Unterstützt --format=json und --jsonpath.
"Notizgarten indizieren oder neu indizieren"ingestSynchronisiert 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

FlagZweckStandard
--top-k NMaximale 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 NHolt ±N benachbarte Chunks um jeden Treffer herum und füllt das context-Array. Verwende 1 oder 2 für die meisten Aufgaben.0
--has-tasksGib nur Chunks zurück, die Aufgabenlisten (Checkboxen) enthalten.aus
--has-codeGib nur Chunks zurück, die eingerahmte Codeblöcke enthalten.aus
--sectionFiltere die Ergebnisse auf Chunks unter einem bestimmten Überschriftspfad (z. B. "Architecture > Components").—
--limit NMaximale Gesamtzahl der zurückzugebenden Ergebnisse.10
--tag "TagName"Nach Tag-Name filtern oder suchen.—
--min-score FUnterdrü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..."
      ]
    }
  ]
}
FeldVorhanden beiBeschreibung
note_slugImmerURL-sicherer Bezeichner, abgeleitet vom Dateipfad.
titleImmerNotiztitel aus Frontmatter oder Dateiname.
file_pathImmerRelativer Pfad innerhalb des Notizgartens.
scoreImmerÄhnlichkeitswert (0–1) für die Suche; Sprunganzahl für Verbindungen.
chunk_indexSuche, versteckt, boostiertWelcher Chunk der Notiz übereinstimmte (0-basiert).
tagsWenn die Notiz Tags hatArray von Tag-Strings.
heading_pathWenn der Chunk unter einer Überschrift istBreadcrumb-Pfad wie "Section > Subsection".
textWenn --include-text übergeben wirdDer vollständige Markdown-Text des übereinstimmenden Chunks, mit erhaltenen Codeblöcken.
contextWenn --context-window N > 0Array von ±N benachbarten Chunk-Texten, geordnet nach Chunk-Index.
extraVerbindungen, Tags, boostiertBefehlspezifische 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:

  1. Suche mit Kontext – führe search mit --context-window 1 --include-text --top-k 2 aus, 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.
  2. Rückverlinkungen für jeden Startpunkt abrufen – führe notebrain backlinks <start-slug> --format json --include-text aus, 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.
  3. Verbindungen nach außen verfolgen – führe notebrain connections <start-slug> --hops 2 --format json aus, 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.
  4. Nach versteckten Links suchen – führe notebrain hidden <start-slug> --include-text --context-window 1 aus, 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.
  5. Synthetisieren, nicht nur auflisten – kombiniere die Startnotiz(en), ihre Rückverlinkungen, ihre connections-Nachbarschaft und alle hidden-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/chroma statt. 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.

Verwandte Skills