Die Regel aus dem März, im November gefunden.

Groundnote ist ein selbst betriebener MCP-Server. Er hält Regeln aus Besprechungen und Mails mit Zitat, Quelle und Datum fest, damit dein KI-Assistent sie wiederfindet.

Auf GitHub ansehen Dokumentation lesen (auf Englisch)

Ein Terminal schickt die Frage eines Kunden nach einem Rahmen in RAL 9005 an ein lokales Groundnote. Die Antwort ist eine Regel aus einer Besprechung im März, mit Zitat, Sprecherin und der Minute in der Aufnahme.

Eine echte Suche in einer lokalen Instanz mit erfundenen Daten, formatiert von demo-search-de.hit.jq. Der Rohlauf liegt im Repository.

Wozu

März, Werkstattbesprechung. Mara sagt:

„Mattschwarze Rahmen brauchen zwei Tage länger im Ofen.“

November, ein Kunde schreibt:

„Könnt ihr meinen Rahmen bis Freitag in RAL 9005 lackieren?“

Niemand erinnert sich an die Besprechung, und erst recht nicht daran, dass RAL 9005 der Lack ist, den die Werkstatt mattschwarz nennt.

Groundnote hält den Satz als Regel fest, zusammen mit der Besprechung und der Minute, in der er fiel. Ein Mensch bestätigt ihn einmal. Kommt die Mail, fragt der Assistent Groundnote und bekommt die Regel mit Zitat und Datum zurück. Hat 180 Tage lang niemand die Regel bestätigt oder geprüft (einstellbar), fragt die Antwort, ob sie noch gilt.

Groundnote entscheidet nichts und antwortet niemandem in deinem Namen. Es sagt dir, was wer wann gesagt hat.

Wie es arbeitet

  1. Erfassen

    Das Transkript einer Besprechung oder eine Mail geht an POST /v1/sources und wird so gespeichert, wie es ankam. Zubringer, die das selbst tun, sind noch nicht gebaut. Vorerst ruft dein eigenes Skript die API auf.

  2. Vorschlagen

    Ein Assistent liest den Text und ruft propose_rule mit einer Aussage und einem Zitat auf. Das Zitat muss in der gespeicherten Quelle stehen, sonst wird der Vorschlag abgelehnt. Ein manueller Vorschlag ohne gespeicherte Quelle lässt sich nicht prüfen, die Freigabeseite markiert ihn als ungeprüft.

  3. Freigeben

    Jeder Bereich legt einen Modus fest. In C wartet jeder Vorschlag auf einen Menschen; ohne approval-Block läuft jeder Bereich so. In A und B übernimmt deterministischer Code, was er darf, nie ein Modell. Zahlungsdaten, Widersprüche, Einschleusungssignale und die übrigen Pflichtausnahmen warten in jedem Modus auf einen Menschen.

  4. Antworten

    search_rules liefert die Regel mit Zitat und Quelle, frühere und spätere Fassungen, widersprechende und verwandte Regeln und ihren Platz in deiner Struktur.

Regeln werden nie überschrieben. Eine Änderung ist eine neue Fassung, und die alte verweist auf ihre Nachfolgerin.

Vier Schritte: Eine Besprechung oder Mail wird erfasst, ein Assistent schlägt eine Regel mit Zitat vor, Code übernimmt sie je nach Modus des Bereichs oder ein Mensch gibt sie auf einer eigenen Seite frei, die Suche antwortet mit der Regel und ihrer Quelle.
a
Läuft auf deinem Rechner und ist immer an. Sie kennt Schreibweisen, Wortformen, deutsche Komposita, Tippfehler und deine Synonymliste. So findet „RAL 9005“ die Regel zu „mattschwarz“.
b
Rechnet Regeln und Anfragen mit einem lokalen ONNX-Modell in Vektoren um, das einmal per groundnote model fetch geladen wird, und führt die Ränge mit Stufe a zusammen. Nichts verlässt deinen Rechner. Standardmäßig aus.
c
Schickt die besten Kandidaten an den JEV-Prüfer von TypeSafe AI in den USA, der sie innerhalb eines Monatsdeckels neu ordnet. Standardmäßig aus.

Jede Antwort führt jede Stufe als ran, off, failed, budget oder not-allowed auf. Du siehst also, wenn eine Stufe nicht gelaufen ist.

Stufe a (lexikalisch, lokal) und Stufe b (ein lokales Embedding-Modell, standardmäßig aus) werden zusammengeführt. Stufe c, ein Prüfer in den USA, ist standardmäßig aus. Jede Antwort nennt, welche Stufen gelaufen sind.

Was die Messungen sagen

Stufe a im Vergleich mit einfacher Volltextsuche auf synthetischen Testdaten, die beim Einstellen der Suche nicht benutzt wurden: 300 erfundene Regeln und 137 Anfragen, erst danach geschrieben. Quelle: Bericht zur lexikalischen Suche.

Die letzten beiden Zeilen sind schlechter geworden, das ist der Preis der zusätzlichen Varianten. Die Dokumentation zur Suche zeigt alle Testdaten und was jeder Schritt bringt.

Stufe a auf synthetischen Testdaten aus 300 erfundenen Regeln und 137 Anfragen
Einfache VolltextsucheStufe a, Standardwerte
Relevante Regeln unter den ersten zehn (recall@10)67 %75 %
Rang des ersten relevanten Treffers (MRR, 1,0 = immer zuerst)0,660,80
Veraltete Fassung steht über der aktuellen Regel86 %7 %
Fragen ohne Antwort, die trotzdem einen sicheren Treffer bekommen schlechter17 %25 %
Suchzeit, 95. Perzentil schlechter1,2 ms1,7 ms

Stufen b und c auf synthetischen Testdaten aus 300 Regeln und 180 Anfragen, mit bge-m3, durch die echte Suche. Quelle: Bericht zur semantischen Suche.

Auf diesen Testdaten hilft Stufe b am meisten bei Umschreibungen (recall@5 von 30 % auf 54 %) und bei Fragen in der jeweils anderen Sprache, Deutsch oder Englisch (von 48 % auf 85 %). Nur Stufe c filtert Fragen ohne Antwort heraus.

Nicht alles wird besser. Jede Stufe kostet Suchzeit, und Stufe c drückt einzelne Kategorien: recall@5 fällt bei Anfragen mit Codes von 86 % auf 80 % und bei direkten Fragen von 95 % auf 91 %. Mit geladenem Modell brauchte der Messprozess 6,6 GB Speicher. Die JEV-Aufrufe des ganzen Laufs kosteten 0,06 USD.

Suchstufen auf synthetischen Testdaten aus 300 Regeln und 180 Anfragen
aa + ba + b + c
Relevante Regeln unter den ersten fünf (recall@5)73 %84 %90 %
Rang des ersten relevanten Treffers (MRR)0,830,890,98
Fragen ohne Antwort, die trotzdem einen Treffer bekommen16 von 1616 von 165 von 16
Suchzeit, Median / 95. Perzentil5 / 8 ms25 / 114 ms241 / 309 ms

Datenmodell

Jeder Bereich (ein Team, ein Kundenbereich, ein Projekt) ist eine eigene SQLite-Datei, ohne Abfragen über Dateigrenzen hinweg. Eine Suche über mehrere Bereiche muss man ausdrücklich anfordern, und sie ist nur erlaubt, wenn die Berechtigung alle abdeckt.

Innerhalb eines Bereichs bilden Entitäten wie Kunden, Projekte, Themen und Personen einen Baum beliebiger Tiefe, und Verknüpfungen binden sie an Regeln und Quellen. Mehr dazu in der Dokumentation zum Wissensgraphen.

Ein Bereich ist eine SQLite-Datei. Sie enthält einen Baum aus Entitäten, Regeln mit Fassungen und Quellen mit dem Zitat, aus dem jede Regel stammt.

Sicherheit und Datenschutz

  • Text aus Mails und Transkripten gilt als nicht vertrauenswürdig. Er kann nur zum Vorschlag werden, und Zitate und Namen verlassen den Server nur in gekennzeichneten Blöcken.
  • Keine der 15 MCP-Funktionen kann etwas bestätigen. In den Modi A und B kann nur Code einen Vorschlag übernehmen, und die Pflichtausnahmen warten weiter auf einen Menschen.
  • Secrets kommen nur aus der Umgebung, und der Server startet nicht, wenn andere das Datenverzeichnis lesen können.

Lies das Bedrohungsmodell und den Datenfluss zum Anbieter, bevor du Stufe c einschaltest. Sicherheitslücken meldest du vertraulich wie in SECURITY.md beschrieben.

Schnellstart

Vor dem ersten Release gibt es kein veröffentlichtes Image, du baust es also aus dem Repository. Das läuft im Dev-Token-Modus, der nur für deinen eigenen Rechner gedacht ist. Gib den Port in diesem Modus nie auf einer öffentlichen Schnittstelle frei.

  1. Image bauen

    git clone https://github.com/groundnote/groundnote.git && cd groundnote
docker build -t groundnote .

  2. Starten

    Lege eine groundnote.json mit einem Bereich an und starte den Container im Dev-Token-Modus, nur auf 127.0.0.1 freigegeben.

  3. Bereich anlegen und dir Zugriff geben

    Ohne diese Berechtigung antwortet jeder MCP-Aufruf mit unauthorized.

  4. Claude Code verbinden

    claude mcp add --transport http groundnote http://127.0.0.1:8794/mcp \
  --header "Authorization: Bearer $GN_MCP_TOKEN"

Die Schritte 2 und 3 brauchen eine Konfigurationsdatei und mehr als ein Dutzend Parameter, deshalb stehen sie an einer Stelle: im vollständigen Schnellstart im README, auf Englisch und fertig zum Kopieren.

Stand

Groundnote steht am Anfang und ist noch nicht veröffentlicht. Die API kann sich noch ändern.

Gebaut

  • Suchstufen a, b (lokale Embeddings) und c (JEV-Prüfer mit Monatsdeckel)
  • Freigabeseite mit den Freigabemodi A, B und C für Regeln
  • Wissensgraph mit eigener Prüfseite
  • MCP-Server mit 15 Funktionen und 5 Prompts
  • HTTP-API und Markdown-Export
  • Die CLI groundnote als schlanker API-Client, mit doctor
  • Datensicherung, Wiederherstellungsproben und backup nightly für einen Timer des Betriebssystems, dazu backup verify und restore --to

Noch nicht gebaut

  • API-Anbieter für Stufe b
  • Übernahme von Strukturänderungen in den Modi A und B; Struktur wartet heute immer auf einen Menschen
  • Zubringer für Besprechungen und Mails
  • Überwachung von Litestream durch den Dienst
  • Schwärzung und verschlüsselte Datensicherung

Was als Nächstes kommt, steht im Architekturdokument, an echten Daten gemessene Vorschläge im Fahrplan, Änderungen im Änderungsprotokoll. Die Dokumentation ist auf Englisch.