@dikolab/kbdb

Eine dateibasierte Wissensbasis mit nach Relevanz gewichteter Stichwort- und semantischer (hybrider) Suche. Lernen Sie Ihre Dokumente ein und rufen Sie das relevante Wissen ab. Kein externer Server. Läuft als CLI- und MCP-Server.

📖 Dokumentation · MCP-Setup · CLI-Referenz

GitLab | NPM | JSR | Lizenz: AGPL-3.0

Auf Node.js 20+ oder Deno 2.6+ lauffähig. Kein Datenbank-Server, kein Cloud-Konto — nur Dateien auf der Festplatte.

Was ist kbdb?

kbdb gibt KI-Agenten ein persistentes, durchsuchbares zweites Gehirn. Richten Sie es auf Ihre Markdown-Dokumente, und es indexiert sie in eine dateibasierte Wissensbasis — so rufen Agenten (und Sie) das relevanteste Wissen über eine nach Relevanz gewichtete Stichwort- und semantische Suche ab, nicht über eine exakte Schlüsselsuche. Es ist ein lebendiger Speicher: Agenten lernen neue Fakten, aktualisieren ihr Wissen und rufen es über Sitzungen hinweg ab.

Kein externer Server, den man installieren muss, kein Cloud-Konto — nur Dateien auf der Festplatte. Es läuft überall, wo Node.js oder Deno läuft, und ist als MCP-Server nutzbar, sodass Agenten wie „Claude“ es als Speicher- und Memory-Tool einbinden können.

So funktioniert die Suche: kbdb verwendet standardmäßig die Stichwortsuche — Synonyme werden erweitert, Begriffe nach Relevanz sortiert, und Überschriften fließen mit doppeltem Gewicht (2×) ins Ranking ein. Wenn eine exakte Abfrage nichts findet, lockert kbdb den Abgleich automatisch, sodass Sie trotzdem die besten verfügbaren Ergebnisse bekommen.

Mehr Intelligenz? Mit --algo hybrid kombinieren Sie Stichwortsuche und Similarity-Suche — Ergebnisse erscheinen auch dann, wenn verschiedene Begriffe das gleiche Konzept beschreiben. Der standardmäßige TF-IDF-Embedding-Provider arbeitet komplett offline ohne Einrichtung. Sie können ihn in worker.toml durch einen externen Anbieter ersetzen (lokales ONNX-Modell oder entferntes API), wenn Sie umfangreichere Embeddings benötigen.

Knowledge bleibt aktuell: Wenn Sie eine Datei erneut einlernen, ersetzt kbdb automatisch die alte Version. Die Erkennung von Near-Duplikaten alarmiert Sie, wenn Sie nur, wobei Sie prolongiert bereits besitzeichen — dank dber die Embedding-Ähnlichkeit, die auch umformulierte Fakten findet. kbdb contradictions listet Abschnitte auf, die dasselbe abdecken, sodass Sie sie zusammen lesen können. Integritätsupdates prüfen Prüfsummenze, Waisen und Referenzen. Konfidenzwertschneller helfen Agenten, starketreffer von Schwachen zu unterscheiden.

Related MCP server: Librarian

Erste Schritte

Was Sie brauchen

Eines davon (je nachdem, was Sie bereits möchten):

• Node.js ab Version 20 — Download

• Deno ab Version 2.6 — Download (2.6 ist die Untergrenze: Die Speicher-Engine lädt ihr WebAssembly über Source-Phase-Imports, sodass es nach einem einzigen deno install offline betrieben werden kann. Ältere Deno-Versionen scheitern mit einem irreführenden Module not found-Fehler, der eine .wasm-Datei nennt — obwohl diese vorhanden ist.)

Das war's. Kein Datenbank-Server. Keine weiteren Tools.

Unterstützten

Mit Node.js:

Der CLI-Build ist auf NPM gehostet.

npm install -g @dikolab/kbdb

Mit Deno:

Der CLI-Build auf JSR gehostet.

deno install -Agf jsr:@dikolab/kbdb/cli

Siehe CLI-Installationsanleitung für Voraussetzungen und Überprüfingsschritte.

Probieren Sie es aus

1. Erstellen Sie eine Wissensbasis

kbdb db init --db ./my-kb

Das erzeugt einen .kbdb-Ordner, der all Ihre Daten enthält.

2. Füttern Sie es mit Ihren Dokumenten

kbdb learn ./docs

Zeigen Sie auf einen Ordner mit Markdown-Dateien. kbdb liest sie, zerlegt sie in Abschnitte und baut einen Suchindex auf. Ergänzen Sie --tags design,v2, um Abschnitte zu markieren, --replace, um vorhandene Abschnitte aus derselben Quelle zu aktualisieren, oder --level 2, um die hierarchische Tiefe zu definieren (1 = breitest, 6 = feinste). Beim Erlernen eines Verzeichnisses wird die Ebene automatisch aus der Ordentstiefe erkannt.

3. Suchen

kbdb search "how does auth work"

Ergebnisse sind nach Relevanz sortiert, und Treffer zeigen, worin die Begriffe matchten. Standardmäßig mit --format rec (recfile: ein field: value pro Zeile) the Ausgabe leicht „diggen“ lässt. Weitere Formate: json (maschinenlesbar), text (nummerierte Liste) und mcp (JSON-RPC-2.0-Hülle). Mit --offset blättern Sie durch große Ergebnismengen.

Hybridsuche ausprobieren (Stichwort + KI-Ähnlichkeit):

kbdb search "how does auth work" --algo hybrid

Tipp: --db ist für die CLI optional. kbdb steigt von Ihrem Arbeitsverzeichnis aus zum nächstelegenen .kbdb-Ordner auf, sodass makegramme überall in einem Projekt funktionieren. Mit einem --db <dir> (übergeordnetes Verzeichnis von .kbdb) legen Sie eine bestimmte Basis fest, oder setzen Sie KBDB_DB_DIR. Nur der mcp-Server verlangt einexplizisches --db — er durchsucht nie das Arbeitsverzeichnis.

Basisübergreifende Suche: Reichern Sie Ergebnisse mit nur-lesefähigem Wissen aus anderen Datenbanken an, Nutzen Sie dafür --other-db <dir> (wiederholbar) oder --cascade, um zusätzlich aus den .kbdb-Ordnern in übergeordnet Verzeichnissen zu laden:

kbdb search "how does auth work" \
   --other-db ~/shared-kb --cascade

Jedes Ergebnis trägt ein source_db-Feld — die Wurzel der Datenbank, aus der es stammt — das Sie direkt wieder in --db oder --other-db einfügen können.

Skripting: Fügen Sie --format json hinzu, um eine strukturierte JSON-Ausgabe zur Weiterverarbeitung zu erhalten. Mit --non-interactive oder KBDB_NON_INTERACTIVE=1 unterdrücken Sie Prompt si in CI-Pipelines.

4. Kontext abrufen

kbdb recall <kbid> --depth 1

Beginnen Sie mit dem kbid eines Suchergebnisses und erweitern Sie den Kontext stufenweise: Stufe 0 liefert den Abschnitt selbst, Stufe 1 fügt übergroordnete Dokumente und Rückverweise hinzu, Stufe 2 fügt nebengeordnete Dokumente und Vorwärtsverweise, Stufe 3 den Volltext der referenzierten Abschnitte.

Wissensbasis

Bauen, durchsuchen und pflegen Sie Ihren Wissensspeicher.

• Importieren — Markdown- und Textdateien mit Tags und Herkunftsverfolgung importieren

• Intelligente Aktualisierung — Neues Lernen einer Datei ersetzt die alte Version, statt sie zu duplizieren

• Verlauf — Ein ersetzte Abschnitt wird zurückgezogen, nicht gelöscht: kbdb history betretet die Kette von beiden Enden, und eine alte kb-id löscht weiter auf

• Suchen — drei Verfahren: Stichwort (Standard), KI-Ähnlichkeitssuche oder hybrid (beide)

• Automatischer Fallback — Wenn eine exaktige Abfrage nichts findet, erweitert kbdb automatisch den Treffbereich

• Recall — Abschnitte mit progressivem Kontext auf deren Snippet bis zur vollen Konversation, abhängig vom --limit-Budget

• Messen — kbdb eval prüft Metricen wie Recall@k, MRR und nDCG@k an Ihrem Testdatensatz und gibt einen Nicht-Null-Exit zurück, wenn eine Änderung die Ergebnisrangordnung verschlechtert

• Nachbarschaft — kbdb neighborhood gibt an, was in einemAbschnitt zusammenhängt und wie: achtverknüpfte Kanten, sieben aufgezeichnet, eine abgeleitet

• Konsolidieren — kbdb consolidate schlägt vor, welche Abschnitten zusammengefasst werden könnten; es macht nur Vorschläge — Sie schreiben den Merge selbst

• Exportieren — Wissensbasis für Backups exportieren

• Verifizieren — Integrität prüfen und veraltete Daten bereinigen

• Rebuild — Indizes neu aufbauen, falls etwas schiefgegangen ist

Siehe die Wissensbasis-Anleitung für die vollständige Durchführung, einschließlich Export und Backup.

Agenten-Tooling

MCP-Schnellstart (Kunde CLI):

claude mcp add kbdb -- \
   npx @dikolab/kbdb mcp --db /path/to/project

MCP-Einrichtung

Konfigurationsdateien für Claude Code, VS Code und Claude Desktop sowie Anleitungen zur Fehlerbehebung finden Sie in der MCP-Installationsanleitung.

• MCP-Server mit 30 Tools — Suchen, Abrufen, Lernen, Revidieren, Nachholen, Widersprüche, Export, Skills/agents suchen und mehr

• Skills — speichert wiederverwendbare Prompt-Vorlagen mit ausfüllbaren Platzhaltern

• Agents — ein KI-Agent-Profil, das ein Persönlichkeit mit Skills kombiniert

• Capture-Richtlinie — Server mit Agenten MCP-Handshake Eigenes zu speichern; keine Konfiguration mehr auf dem Host. Zwei der sechs Klauseln handeln davon, was nicht zu speichern ist: Chat-Zusammenfassungen, Annahmen, Geheimnisse und alles, was der Code schon sagt. kbdb liefert die Richtlinie; ob Agenten sie befolgen, kannes nicht erzwungen

• Auto-Capture — kann das eigee Modell des Hosts bitten, Wissen auszulesen, das es speichern wert ist. Das braucht das MCP-sampling-Möglichkeit, und Claude Code advertises es nicht ab, daher ist Auto-Capture in diesem Kontext nicht aktiv. Alle anderen Features dieser Liste bleiben davon unberührt — siehe Host-Support

• Daemon-Resilienz — konfigurierbar Request-Timeout und automatischer Retry mit Daemon-Restart

• Lebenszyklus des Worker-Daemons — den Hintergrund stoppen und neu starten

• Granulare Deno-Berechtigungen — der Prozess läuft mit begrenzten Berechtigungen statt mit --allow-all

• Path-Absicherung — der Daemon wehrt Pfad-Traversal (..) beim Export/Import ab

Was der Server dem Agenten mitteilt. Die initialize-Antwort enthält eine instructions-Zeichenkette — Zugriff auf den einzigen Bereich, der jeder konformen Berechtigung von MCP gezielt ohne Konfiguration zur Verfügung steht. kbdb weist sie der Capture-Richtlinie zu: erst suchen, dann eine unanswered-Entscheidung als Lücke, nach der man das Gefühl untersucht statt zu raten; Entscheidungen und Korrekturen speichern, deren Wiederfinden echte Mühle erfordert; und speichern Sie nicht, was der Code bereits ausdrückt. Dieselben Sätze werden in den Tool-Beschreibungen von learn, revise und search wörtlich zitiert statt umschrieben, sodass alles in einer Quelle belegt.

Weitere Informationen in der Agent-Tooling-Anleitung für MCP Setup, Skills, Agents und Library-API sowie zur Capture Policy für den vollständigen Richtlinientext und die warum sie nur einmal formuliert ist.

For Developers

Für Entwicklerinnen und Entwickler

Library API

Verwenden Sie kbdb programmatisch in Ihrem Node.js- oder Deno-Projekt:

import { createWorkerClient } from '@dikolab/kbdb';

// Spawns a background worker if not already running
const client = await createWorkerClient({
   contextPath: '/path/to/.kbdb',
   requestTimeoutMs: 30_000,
});

const results = await client.search({
   query: 'authentication',
   limit: 10,
   offset: 0,
});

console.log(results.items);
client.disconnect();

Geben contextPath (../kbdb-Verzeichnisindex) oder dbPath (das parent directory, in dessen Unterordnung .kbdb gefunden wird) an.

Den vollständigen API-Referenz finden Sie in der Bibliothek-API-Referenz.

Entwicklungsumgebung einrichten

git clone https://gitlab.com/diko316/knowledge-base-db.git
cd knowledge-base-db
npm install
npm test

Docker

Zwei Dockerfiles, and sie sind nicht austauschbar.

Dockerfile an der Repository wurde als MCP-Server gebaut — diejenige, die für MCP-Verzeichnisse verwendet wird, und die Datei, die Sie beim Einsatz in einen Container with kbdb verwenden. Siehe MCP-Installation für die Host-Konfiguration und für Grund, warum ein benanntes Volume (Named Volume) statt eines Bind-Mount benötigt wird.

Dockerfile.tooling baut die Entwicklungs-Toolchain (Node.js und Deno), wie jedes make-Ziel sie über docker-compose.yaml anspricht:

HOST_UMASK=$(umask) docker compose run --rm tool sh

Führen Sie make benchmark aus, um Such- und Rebuild-Latenz in großem Maßstab zu messen — Ergebnisse werden automatisch in docs/benchmark/benchmark.md geschrieben.

Für alle weiteren Build-Ziele siehe Makefile.

Beitrag

1. Forken Sie das Repository.

2. Erstellen Sie einen Feature-Branch.

3. Nehmen Sie Ihre Änderungen vor und fügen Sie Tests hinzu.

4. Führen Sie npm test und npm run lint aus.

5. Auf dem Gitlab eröffnen Sie einen Merge-Request.

Dokumentation

• Second Brain mit Claude Code -- der kanonische Einrichtungsleitfaden: Aufbau des Arbeitsbereichs, korrekte Befehle, MCP-Anbindung

• CLI-Installationsanleitung -- Voraussetzungen, npm/JSR-Installation, Verifikation

• Wissensdatenbank-Leitfaden -- Importieren, Suchen, Abrufen, Exportieren

• Leitfaden für Agent-Tooling -- MCP, Skills, Agenten, Bibliotheks-API

• CLI-Referenz -- vollständige Befehlsliste mit Beispielen

• MCP-Installationsanleitung -- Claude CLI, Claude Code, VS Code, Claude Desktop

• MCP-Server-Leitfaden -- Einrichtung, Werkzeuge, Umgebungskonfiguration und was der Server einem Agenten bei initialize mitteilt

• Host-Unterstützung -- welche MCP-Hosts die Capture-Richtlinie bereitstellen und Sampling ankündigen, gemessen nicht angenommen

• Capture-Richtlinie -- was kbdb einem Agenten zum Speichern mitteilt und warum es nur einmal angegeben wird

• Suche und Ranking -- wie die Suche unter der Haube funktioniert

• Speicherarchitektur -- Dateiformate, Verzeichnislayout und was die beibehaltene Historie kostet

• Deno-Berechtigungen -- die Berechtigungsflags, die kbdb benötigt, und warum

• Benchmark-Ergebnisse -- Such- und Neuaufbau-Latenz bei Skalierung

• Lern-Skalierung -- wie die Lernkosten mit der Korpusgröße wachsen

• Widerspruchssignale -- Kalibrierung der Schwellenwerte für Beinahe-Duplikate und Widersprüche über 1128 beschriftete Paare

• Versionshinweise

• Architekturübersicht

Die Suchmaschine

Speicherung, Indexierung und Ranking stammen von @dikolab/vdb, kbdb' Schwesterproject desselben Autors. Seine Dokumentation deckt die Abruf-Seite ausführlich ab:

• vdb-Übersicht -- Speichermodell, Partitionen, BM25F, Vektor- und Hybridsuche

• vdb-Beispiele -- durchgearbeitete Abfragen und Ranking-Verhalten

Unterstützung

kbdb ist freie, unter AGPL lizenzierte Software. Wenn es einen Platz in Ihrem Workflow verdient, können Sie die laufende Entwicklung über PayPal unterstützen.

Lizenz

Dieses Projekt ist doppelt lizenziert:

• Open Source unter der GNU Affero General Public License v3.0 (AGPL-3.0-only)

• Kommerzielle Lizenz verfügbar für Closed-Source- oder SaaS-Nutzung

Versionen <= 0.5.0 bleiben unter der ISC-Lizenz.

Siehe LICENSING.md für Details und Kontaktinformationen.