kg – lokaler Wissensgraph für deine KI-Assistenten

Beta – APIs können sich noch ändern und einige Fehler sind noch zu erwarten.

kg gibt deinem KI-Assistenten einen persistenten, strukturierten, bearbeitbaren Projektspeicher, der lokal als Wissensgraph gespeichert wird.

Anstatt sich nur auf das Abrufen von Dokumentabschnitten zu verlassen, kannst du Architektur, Entscheidungen, Vorfälle, Regeln, Abhängigkeiten und Arbeitsabläufe in einem Graphen speichern, der lesbar, überprüfbar und Git-freundlich ist.

Verwende es, wenn dein Assistent ein bestehendes Projekt über Sitzungen hinweg verstehen soll – nicht jedes Mal von Null anfangen.

Warum es verwenden

• Persistenter Speicher – Projektwissen zwischen Gesprächen behalten

• Strukturiert, nicht vage – Knoten, Kanten, Fakten und Lücken direkt prüfen

• Bearbeitbar und überprüfbar – Graphen als *.kg-Dateien mit lesbaren Diffs speichern

• Lokal zuerst – dein Projektwissen bleibt in einem Git-freundlichen Format auf deinem Rechner

• Funktioniert mit MCP-Clients – als lokaler stdio-MCP-Server anschließen

Related MCP server: Agentic Memory Server

Warum nicht einfach RAG

Klassisches RAG ist gut zum Abrufen von Textabschnitten aus Dokumenten.

kg-mcp ist besser, wenn du Folgendes möchtest:

• stabilen Projektspeicher statt wiederholtem Abruf

• explizite Fakten, Beziehungen und Abhängigkeiten

• Graphaktualisierungen während der echten Arbeit mit dem Assistenten

• etwas, das du im Laufe der Zeit prüfen, versionieren, diffen und verbessern kannst

Installation

Von crates.io

cargo install kg-cli

Vom Skript

Empfohlene Installation:

curl -sSL https://raw.githubusercontent.com/nnar1o/kg/master/install.sh | sh

Du kannst auch ein fertiges Binärpaket von GitHub Releases herunterladen.

kg-mcp mit deinem KI-Client verbinden

Füge kg-mcp als lokalen stdio-MCP-Server hinzu.

Beispielkonfiguration:

{
  "mcpServers": {
    "kg": {
      "command": "/absolute/path/to/kg-mcp"
    }
  }
}

Danach:

1. starte deinen KI-Client neu,

2. bestätige, dass der kg-MCP-Server verfügbar ist,

3. beginne mit den untenstehenden Prompts.

Vollständige MCP-Einrichtung und Referenz: docs/mcp.md

SCL-Schnellstart

kg versteht kurze, verb-erste englische Befehle (SCL – Simple Command Language). Der aktive Graph wird automatisch aus deiner Konfiguration ermittelt.

find "compressor defrost"
get concept:refrigerator
add concept:smart_fridge --name "Smart Fridge" --description "Connected refrigerator"
modify concept:smart_fridge --importance 0.9
remove concept:old_idea
connect process:compressor_control TRIGGERS process:auto_defrost
disconnect process:compressor_control TRIGGERS process:auto_defrost
list nodes
stats
use fridge
help

Kernverben

IDs

Format: <type>:snake_case – z. B. concept:fridge, bug:door_seal, process:compressor_cycle.

Beziehungen

HAS USES STORED_IN TRIGGERS CREATED_BY AFFECTED_BY AVAILABLE_IN DOCUMENTED_IN DEPENDS_ON TRANSITIONS DECIDED_BY GOVERNED_BY READS_FROM

Tipps

• Flags stehen nach den Positionsargumenten. Setze mehrwortige Werte in Anführungszeichen.

• Trenne Befehle mit ; oder Zeilenumbrüchen. Zeilen, die mit # beginnen, sind Kommentare.

• Verwende use <graph>, um innerhalb eines Skripts den Graphen zu wechseln.

• Die kanonischen kg <graph> node find ...-Befehle funktionieren weiterhin als Fallback.

• Vollständige SCL-Referenz: docs/scl.md

Einen Graphen generieren

Dies ist der erste Workflow für ein neues Projekt: Bitte den Assistenten, einen Graphen aus deiner Dokumentation zu erstellen oder zu erweitern.

Standardmäßig werden Graphen in ~/.kg/graphs als *.kg-Dateien gespeichert.

Minimaler Prompt:

You are connected to kg-mcp.

Project graph name: payments

Build or extend this graph from the project documentation I provide.
Use `payments` as the graph name for all graph operations.

Only add facts grounded in source material.
If an important fact is missing and can be inferred safely from the provided docs, update the graph.
If something is ambiguous, ask or record it as a note instead of inventing facts.

Beispiel-Prompt mit Dokumenten:

Use kg-mcp to build or extend the `payments` graph from these documents:
- docs/payments/overview.md
- docs/payments/retries.md
- docs/payments/providers.md

Only add facts grounded in the documents.
If something is ambiguous, keep it out of the graph or record it as a note.
When you finish, summarize what was added, what remains unclear, and what document should be ingested next.

Längerer Prompt für diesen Workflow: docs/ai-prompt-graph-from-docs.md

Für ein fertiges Repository-Beispiel führe cargo run --bin repo-example aus, um repo-example.kg aus diesem Repository zu generieren.

Automatischer Graph für ein Verzeichnis

kg kann einen vorhandenen Ordner automatisch in einen Graphen umwandeln. Es durchsucht den Verzeichnisbaum, erkennt viele gängige Dateitypen, extrahiert Symbole für Rust, Java, JavaScript/TypeScript, Python und C/C++ und hält die generierte Struktur getrennt vom manuellen Graphen.

Für markdown-ähnliche Dokumente erstellt es auch Dokument- (GDOC) und Kapitel-Knoten (GSEC) mit Abschnittsinhalten.

Es ist ein schneller Weg, eine nützliche Karte einer Codebasis oder eines Arbeitsbereichs zu erhalten, ohne alles von Hand zu modellieren. Der generierte Index ist lokal, aktualisierbar und kann in Git bedenkenlos ignoriert werden.

Beispiel:

cargo run --bin repo-example

Dies generiert repo-example.kg aus diesem Repository als lokale Demo.

Den Assistenten nach Fakten im Graphen fragen

Sobald der Graph existiert, besteht der normale Workflow darin, den Assistenten zu bitten, ihn zu prüfen und Fragen daraus zu beantworten.

Beispiel-Prompt:

Use kg-mcp to inspect my existing `payments` graph.

I want to understand:
- how payment authorization works,
- what triggers retries,
- which external providers are involved,
- which datastore reads and writes are part of the flow.

If the graph is missing critical information, say exactly what is missing.

Andere nützliche Fragen:

• „Welche Regeln steuern Wiederholungen im payments-Graphen?“

• „Welche Systeme schreiben in den Orders-Datenspeicher?“

• „Was fehlt oder ist schwach in diesem Graphen?“

• „Welche Knoten und Kanten erklären den Autorisierungsablauf?“

Fakten über den Assistenten hinzufügen oder aktualisieren

Du kannst den Assistenten auch bitten, den Graphen zu verbessern, während du arbeitest.

Beispiel-Prompt:

Use kg-mcp to review my existing `payments` graph.

Find:
- missing important nodes,
- weak descriptions,
- missing facts,
- suspicious or low-value edges.

Apply safe improvements where possible.
Only add facts grounded in the graph, the provided docs, or the current discussion.
If something is ambiguous, leave it out or add a note.

When you finish, summarize:
- what was wrong,
- what you changed,
- what still needs manual review.

Dies funktioniert am besten, wenn dein Haupt-Systemprompt oder Projektprompt dem Assistenten bereits mitteilt, welcher Graph zum Projekt gehört.

Minimaler Projekt-Prompt:

You are connected to kg-mcp.
Project graph name: payments.
Use this graph for relevant reads and updates in this project.
If you notice important missing information that is grounded in the available docs or conversation context, update the graph as part of your work.
If uncertain, ask or add a note instead of inventing facts.

Tipps

Projektkonfiguration (.kg.toml)

kg sucht in kg.toml im aktuellen Verzeichnis und seinen übergeordneten Verzeichnissen.

Beispiel:

backend = "json" # json backend writes native .kg files by default
graph_dir = ".kg/graphs"
graph_dirs = ["../shared-graphs", "../team-graphs"]
nudge = 20
user_short_uid = "dev_01"

[graphs]
payments = "graphs/payments.kg"

Hinweise:

• backend = "json" ist die Standardeinstellung und bevorzugt .kg-Textgraphen.

• backend = "redb" speichert Graphen in .db-Dateien.

• graph_dir legt ein primäres Graphverzeichnis fest.

• graph_dirs fügt zusätzliche Verzeichnisse hinzu, die von kg list und der Graphauflösung durchsucht werden.

Graphen in Git aufbewahren

Das Standard-Graphverzeichnis ist ~/.kg/graphs.

Du kannst dieses Verzeichnis unter Git stellen.

Empfohlener Ansatz:

• die Haupt-*.kg-Graphdateien in Git aufbewahren,

• generierte Sidecars und lokale Betriebsdateien ignorieren,

• Backup-Snapshots und Ereignisprotokolle als lokale Maschinenhistorie behandeln, es sei denn, du möchtest sie explizit versionieren.

Vorgeschlagene .gitignore:

*.kglog
*.kgindex
*.event.log
*.migration.log
*.bak
*.bck.*.gz

In der Praxis:

• *.kg ist die Haupt-Graphdatei, die du normalerweise überprüfen und committen möchtest,

• *.kglog ist ein lokales Zugriffs-/Feedback-Protokoll,

• *.kgindex ist ein generierter lokaler Index,

• *.event.log ist eine lokale, nur anhängbare Änderungszeitleiste,

• *.bak ist die vorherige Version auf der Festplatte vom letzten Schreibvorgang,

• *.bck.*.gz sind periodische komprimierte Backup-Snapshots,

• *.migration.log ist ein Migrationsbericht, wenn ältere Graphen konvertiert werden.

*.kg ist Git-freundlich und bewusst so strukturiert, dass Diffs lesbar und Merges einfacher sind, wenn mehrere Personen am selben Graphen arbeiten.

Einen Graphen nach HTML exportieren

Um eine interaktive HTML-Ansicht eines Graphen zu generieren:

kg graph payments export-html --output payments.html

Du kannst das generierte HTML als teilbaren visuellen Schnappschuss des aktuellen Graphen aufbewahren.

Dokumentation

• docs/mcp.md – MCP-Einrichtung und Tool-Referenz

• docs/ai-prompt-graph-from-docs.md – längerer Prompt für die Dokumentaufnahme

• docs/build-graph-from-docs.md – Workflow zum Erstellen von Graphen aus Dokumenten

• docs/troubleshooting.md – häufige Probleme

Kontakt

Bei Fragen oder Feedback: nnar10@proton.me