Waggle-mcp

Warum waggle-mcp?

Die meisten LLMs vergessen alles, sobald das Gespräch endet. waggle-mcp behebt dies, indem es Ihrer KI einen persistenten Wissensgraphen gibt, den sie über jeden MCP-kompatiblen Client lesen und beschreiben kann.

Waggles Hauptvorteil ist die Token-Effizienz bei strukturiertem Kontext:

Hinweis zum Abruf: Waggle tauscht etwas rohe Abrufabdeckung gegen dramatisch niedrigere Token-Kosten und reicheren relationalen Kontext ein. Siehe den Benchmark-Abschnitt für ehrliche Zahlen.

Schnellstart — 30 Sekunden

pip install waggle-mcp
waggle-mcp init

Der init-Assistent erkennt Ihren MCP-Client, schreibt dessen Konfigurationsdatei und erstellt das Datenbankverzeichnis — keine JSON-Bearbeitung erforderlich. Unterstützt Claude Desktop, Cursor, Codex und einen generischen JSON-Fallback.

Starten Sie nach der Initialisierung Ihren MCP-Client neu, und Ihre KI verfügt über einen persistenten Speicher. Kein Cloud-Dienst. Kein API-Schlüssel. Die semantische Suche läuft vollständig lokal.

In Aktion sehen

Hier ist ein konkretes Vorher/Nachher für einen Entwickler, der die KI täglich nutzt:

Sitzung 1 — 10. April

User:  Let's use PostgreSQL. MySQL replication has been painful.
Agent: [calls observe_conversation()]
       → stores decision node: "Chose PostgreSQL over MySQL"
       → stores reason node:   "MySQL replication painful"
       → links them with a depends_on edge

Sitzung 2 — 12. April (frisches Kontextfenster, keine Historie)

User:  What did we decide about the database?
Agent: [calls query_graph("database decision")]
       → retrieves the decision node + linked reason from April 10

       "You decided on PostgreSQL on April 10. The reason recorded was
        that MySQL replication had been painful."

Sitzung 3 — 14. April

User:  Actually, let's reconsider — the team is more familiar with MySQL.
Agent: [calls store_node() + store_edge(new_node → old_node, "contradicts")]
       → conflict is flagged automatically; both positions are preserved in the graph

Der Agent benötigte nie explizite Anweisungen zum Merken oder Abrufen — er rief die richtigen Tools basierend auf dem Gespräch auf, und der Graph lieferte ihm den richtigen Kontext.

Funktionsweise

Speicher wird nicht einfach nur gespeichert — er durchläuft einen Lebenszyklus:

You talk to your AI
        │
        ▼
  observe_conversation()          ← AI drops the turn in; facts extracted via structured LLM (regex fallback)
        │
        ▼
  Graph nodes are created         ← "Chose PostgreSQL" becomes a decision node
  Edges are inferred              ← linked to the "database" entity node
        │
        ▼
  Future conversation starts
        │
        ▼
  query_graph("DB schema")        ← semantic search finds the node from 3 sessions ago
        │
        ▼
  AI answers with full context    ← "You decided on PostgreSQL on Apr 10, here's why…"

Jeder Knoten trägt semantische Einbettungen, die lokal mit all-MiniLM-L6-v2 berechnet werden — einem schnellen, leichtgewichtigen Modell, das vollständig auf dem Gerät läuft, ohne dass ein API-Schlüssel oder Netzwerkaufruf erforderlich ist. Das bedeutet, die semantische Suche funktioniert offline, kostet pro Abfrage nichts und hält Ihre Daten privat.

Das magische Tool: observe_conversation

Dies ist das Tool, das Sie am häufigsten verwenden werden. Sie müssen Fakten nicht manuell speichern — weisen Sie den Agenten einfach an, jeden Gesprächsverlauf zu beobachten, und er erledigt den Rest.

observe_conversation(user_message, assistant_response)

Unter der Haube:

1. Extrahiert atomare Fakten aus beiden Seiten des Gesprächs

2. Entfernt Duplikate gegenüber bestehenden Knoten mittels semantischer Ähnlichkeit

3. Erstellt typisierte Kanten zwischen verwandten Konzepten

4. Markiert Widersprüche zu bestehenden gespeicherten Überzeugungen

Keine Anweisungen erforderlich. Kein Schema zu definieren. Einfach beobachten.

Unter der Haube führt jeder Aufruf einen Pydantic-validierten LLM-Extraktionsdurchlauf (mit einem Regex-Fallback) aus, um strukturierte Fakten aus unordentlichen Dialogen zu ziehen.

Beispiel: "Lass uns PostgreSQL verwenden, weil MySQL-Replikation zu schmerzhaft ist."

{
  "facts": [
    {
      "label": "PostgreSQL for generic events",
      "content": "Chose PostgreSQL over MySQL because MySQL replication is too painful.",
      "node_type": "decision",
      "confidence": 0.95,
      "tags": ["llm-extracted", "confidence:0.95"]
    }
  ]
}

Jede Extraktion mit confidence < 0.5 oder einem ungültigen Schema wird stillschweigend verworfen, um Halluzinationsrauschen zu vermeiden.

Speichermodell

Knotentypen — was gespeichert wird:

Kantentypen — wie Knoten verbunden sind:

relates_to · contradicts · depends_on · part_of · updates · derived_from · similar_to

MCP-Tools

Ihre KI ruft diese direkt auf — Sie müssen sie nicht manuell verwenden.

Performance & Benchmarking

Alle unten stehenden Zahlen sind reproduzierbar anhand der eingecheckten Fixtures in benchmarks/fixtures/ unter Verwendung des Harness unter scripts/benchmark_extraction.py. Gespeicherte Ausgabe-Artefakte befinden sich in tests/artifacts/.

Ein Befehl erzeugt alle unten stehenden Tabellen (Extraktions-Regex-Baseline, Abruf, Deduplizierung und der Pilot zur vergleichenden Token-Effizienz):

PYTHONPATH=src .venv/bin/python scripts/benchmark_extraction.py \
  --extraction-backend regex \
  --systems waggle rag_naive \
  --output tests/artifacts/benchmark_current.json

Die LLM-Extraktionszeile (75%) erfordert einen separaten Durchlauf mit einer lokalen Ollama-Instanz — sie ist nicht in benchmark_current.json enthalten:

# Requires Ollama running locally with qwen2.5:7b pulled
PYTHONPATH=src .venv/bin/python scripts/benchmark_extraction.py \
  --extraction-backend llm --ollama-model qwen2.5:7b --ollama-timeout-seconds 30

Extraktionsgenauigkeit

Korpus: 12 Dialogpaare, die einfache Erinnerung, Unterbrechungen, Umkehrungen, vage Aussagen und widersprüchliche Signale abdecken (benchmarks/fixtures/extraction_cases.json).

Abrufgenauigkeit

Korpus: 18 Knoten, 18 Abfragen — 6 einfach (direkte Paraphrasierung) und 12 schwer (adversariell: semantische Verallgemeinerung, zeitliche Disambiguierung, indirekte Domänenübersetzung, Privatsphäre-Framing). Quelle: benchmarks/fixtures/retrieval_cases.json.

Token-Effizienz vs. naive gechunkte Vektor-RAG

Die obige Tabelle zur Abrufgenauigkeit misst die eigenständige Suchqualität von Waggle. Der Vergleich unten verwendet einen separaten Multi-Sitzungs-Korpus, der darauf ausgelegt ist, die Token-Effizienz gegenüber einer gechunkten Vektor-Baseline zu testen.

Korpus: 24 Multi-Sitzungs-Szenarien, 66 Abruf-Abfragen über 7 Aufgabenfamilien (benchmarks/fixtures/comparative_eval.json).

Waggle verwendet ~4× weniger Token pro Abruf als die naive gechunkte Baseline in diesem Korpus.

Die Lücke zwischen Waggles Hit@k (91%) und der exakten Unterstützung (74%) zeigt, dass der Graph-Abruf das richtige Thema findet, aber manchmal unzureichende unterstützende Details zurückgibt — am deutlichsten bei cross_scenario_synthesis-Abfragen (8/8 Treffer, 1/8 exakt). Die Verbesserung der Kontextzusammenstellung — insbesondere die Kantendurchlauf-Tiefe und die Multi-Hop-Teilgraphen-Erweiterung — ist ein verfolgter nächster Schritt.

Der Kompromiss ist ehrlich: Die gechunkte Baseline erreicht 100% Hit@k in diesem Korpus, da bei top_k=5 jeder Fakt aus seinem eigenen Sitzungs-Chunk abrufbar ist. Der Vorteil der Token-Effizienz ist real und reproduzierbar; der Anspruch auf Überlegenheit beim Abruf erfordert einen Korpus, bei dem die Chunk-Abdeckung nicht für fehlenden relationalen Kontext kompensieren kann. Die Korpus-Härtung läuft.

Wenn die Extraktion fehlschlägt

Benutzer: "Ja, lass uns einfach das Ding machen, über das wir gesprochen haben."

Das LLM weist mehrdeutigen Eingaben ein geringes Vertrauen (confidence < 0.5) zu; Waggle verwirft die Extraktion stillschweigend, anstatt eine Vermutung zu speichern. Die Pipeline greift bei einem Timeout nicht stillschweigend auf Regex zurück — Backend-Fehler treten als explizite Fehler auf, die protokolliert werden.

Korpus: 22 Knotenpaare — 11 echte Duplikate (Synonym, Paraphrase, Domänenäquivalenz) und 11 falsche Freunde (gleiche Technologiekategorie, unterschiedliche Technologie). Quelle: benchmarks/fixtures/dedup_cases.json.

Die Pipeline durchläuft fünf Ebenen:

1. Ebene 0 — Entitätsschlüssel-Hard-Block — wenn beide Knoten unterschiedliche Technologien in der gleichen Kategorie benennen (z.B. postgresql vs mysql), wird die Zusammenführung bedingungslos blockiert.

2. Ebene 0b — Numerischer Konfliktschutz — gleiche Entität, aber unterschiedliche kritische Zahlen (z.B. jwt 15 Min vs 1 Std) → blockieren. Schützt davor, unterschiedliche Fakten zusammenzuführen, die eine Technologie teilen, sich aber in einem Schlüsselwert unterscheiden.

3. Ebene 1 — Exakter String-Abgleich — normalisierter Inhalt oder Label-Gleichheit.

4. Ebene 2 — Teilstring-Enthaltung — ein Satz ist eine strikte Teilmenge des anderen.

5. Ebene 3 — Semantische Ähnlichkeit — Kosinus via all-MiniLM-L6-v2:

   • Aggressiver Pfad für gleiche Entitäten: wenn beide auf denselben Entitäts-Token verweisen, Zusammenführung bei Kosinus ≥ 0.60 (erfasst Paraphrasen-Echt-Duplikate wie "fastapi wurde gewählt" / "wir haben fastapi gewählt, weil async")

   • Typ-bewusster Schwellenwert: decision/preference → 0.82; fact → 0.92; entity → 0.97

   • Jaccard-verstärkter Pfad: Wortüberschne