MCP-Server für Agentengedächtnis: Claude Code mit HotKV verbinden

Ein MCP-Server ist der einfachste Weg, einem KI-Assistenten ein Gedächtnis zu geben, das länger hält als ein Chat. Claude Code, Cursor und ähnliche Clients verlieren den Kontext eines Chats, wenn er endet. Ihnen dafür rohen Datenbankzugriff zu geben, ist riskant. hotkv-mcp ist unser quelloffener MCP-Server für HotKV. Er gibt einem Assistenten einen festen Satz von Werkzeugen für Notizen, Gesprächsverlauf, ein Ereignisprotokoll, Prompt-Vorlagen und Dokumentensuche. Mehr bietet er nicht.

Kurz gesagt. hotkv-mcp ist ein MCP-Server unter Apache-2.0, der Claude Code, Cursor, VS Code oder Ihren eigenen Agenten über 28 feste Werkzeuge mit einem HotKV-Server verbindet. Es gibt kein Werkzeug, das einen beliebigen Befehl ausführt, der Assistent kann also weder Daten leeren noch die Konfiguration ändern. Ein Nur-Lese-Modus entfernt jedes schreibende Werkzeug, und ein Namensraum beschränkt den Agenten auf ein Schlüsselpräfix. Installieren Sie ihn mit pip install hotkv-mcp oder starten Sie ihn mit uvx.

Was das Model Context Protocol ist

Das Model Context Protocol, kurz MCP, ist ein offener Standard, um KI-Anwendungen mit externen Systemen wie Datenquellen, Werkzeugen und Workflows zu verbinden. Die Einführung des Projekts vergleicht es mit einem USB-C-Anschluss für KI-Anwendungen. In der Sprache von MCP ist die Anwendung der Client, und jedes System, mit dem sie sich verbindet, wird von einem Server bereitgestellt.

Für Gedächtnis heißt das, dass der Assistent ein benanntes Werkzeug aufruft, etwa eines, das eine Notiz speichert. Der Server entscheidet, was dieses Werkzeug darf. Das Modell bekommt nie eine eigene Datenbankverbindung.

Was der HotKV-MCP-Server bereitstellt

Der Server bündelt das Agentengedächtnis, die Prompt-Registry und die Dokumentensuche von HotKV in 28 Werkzeugen. Jedes Werkzeug gibt in seinen MCP-Annotationen an, ob es nur liest, schreibt oder löscht. Ein Client kann dann vor den zerstörerischen eine Freigabe verlangen.

Die Gedächtniswerkzeuge entsprechen den Speichern, die in KI-Agentengedächtnis beschrieben sind, nämlich Gesprächsverlauf, Arbeitsnotizen und Ereignisprotokoll. Semantischer Abruf per Embedding wird nicht bereitgestellt. rag_search sortiert nach Stichwortrelevanz und braucht deshalb keinen.

Die Werkzeuge für Schlüssel, Hashes und Listen funktionieren mit jedem HotKV-Server. Die Werkzeuge für Gedächtnis, Prompts und Dokumentensuche nutzen die KI-Engines von HotKV, die eine Lizenz benötigen, die sie einschließt. Ohne eine solche Lizenz melden diese Werkzeuge, dass der Server für die Funktion nicht lizenziert ist. Die Schlüsselwerkzeuge funktionieren weiter. Die HotKV-Cloud-Instanzen der Tarife Performance und Scale enthalten die KI-Engines, wie die KI-Seite beschreibt.

Installieren und verbinden

Der Server braucht Python 3.10 oder neuer. Er wurde gegen HotKV-Server 0.3.0 und das offizielle Paket hotkv-client geschrieben, und Version 1.0.0 liegt auf PyPI. Installieren Sie ihn mit pip, oder starten Sie ihn ohne Installation mit uv.

pip install hotkv-mcp
uvx hotkv-mcp --url hotkv://localhost:6379

Claude Code

Fügen Sie ihn mit einem Befehl hinzu. Das -- trennt die eigenen Optionen von Claude Code von dem Befehl, der den Server startet, wie die MCP-Dokumentation zu Claude Code beschreibt.

claude mcp add hotkv -- uvx hotkv-mcp --url hotkv://localhost:6379

Cursor und Claude Desktop

Clients, die eine mcpServers-Datei lesen, übernehmen denselben Server als JSON-Eintrag. Halten Sie das Passwort in der Umgebungsvariablen HOTKV_URL oder im Secret-Store des Clients. Eine Kommandozeile ist für andere Nutzer der Maschine sichtbar. Verwenden Sie hotkvs:// für eine TLS-Verbindung.

{
  "mcpServers": {
    "hotkv": {
      "command": "uvx",
      "args": ["hotkv-mcp", "--read-only"],
      "env": { "HOTKV_URL": "hotkv://:your-password@localhost:6379" }
    }
  }
}

Prüfen, ob es funktioniert

Führen Sie claude mcp list aus, um zu bestätigen, dass der Server registriert ist. Bitten Sie dann den Assistenten, das Werkzeug server_info aufzurufen. Es liefert die HotKV-Version und die Speichernutzung, plus die Anzahl der Schlüssel, wenn kein Namensraum gesetzt ist. Außerdem meldet es, ob der Server schreibgeschützt ist und auf welchen Namensraum er beschränkt ist. Damit ist bestätigt, dass Ihre Schutzmaßnahmen greifen.

Den Agenten in sicheren Grenzen halten

Ein Modell, das Werkzeuge aufrufen kann, lässt sich auch dazu überreden, sie zu missbrauchen. Die Grenzen sind deshalb wichtiger als die Funktionen.

Keine beliebigen Befehle

Es gibt kein Werkzeug, das einen rohen Befehl ausführt. Der Assistent kann weder eine Datenbank leeren noch die Konfiguration des Servers ändern, weil keines der 28 Werkzeuge das tut. Er kann jeden Schlüssel lesen, den die Werkzeuge erreichen, weshalb der Namensraum unten wichtig ist.

Nur-Lese-Modus

--read-only entfernt jedes Werkzeug, das schreibt, darunter set, delete, hash_set, list_push, die Gedächtniswerkzeuge, die etwas hinzufügen oder löschen, prompt_save, rag_create und rag_ingest. Der Agent kann sie nicht einmal sehen. Nutzen Sie ihn für Assistenten, die das Gedächtnis befragen, aber nie verändern sollen.

Namensräume und Größenobergrenzen

--namespace PREFIX speichert alles unter diesem Präfix. Der Agent sieht das Präfix nie und kann keine anderen Namen erreichen. Geben Sie jedem Agenten ein Präfix, das nicht der Anfang eines anderen ist. Verwenden Sie agent-a und agent-b, nicht agent und agent:b, sonst kann das kürzere die Namen des längeren erreichen.

Auch die Ergebnisse sind begrenzt. --max-value-bytes kürzt lange Werte und markiert sie als abgeschnitten, mit einem Standardwert von 65.536 Byte. --max-items begrenzt, wie viele Schlüssel, Listenelemente oder Treffer ein Aufruf zurückgibt, standardmäßig 200. Ein einzelner riesiger Wert kann den Kontext des Modells daher nicht überfluten. Das Lesen eines ganzen Hashes ist nicht auf Elemente begrenzt, halten Sie große Hashes also aus dem Namensraum eines Agenten heraus.

Der HTTP-Transport hat keine Anmeldung

Der Standard-Transport stdio wird vom Client als Subprozess gestartet. Für die gemeinsame Nutzung können Sie hotkv-mcp --transport streamable-http ausführen, das auf 127.0.0.1:8000 unter /mcp lauscht. Es authentifiziert Aufrufer nicht. Lassen Sie es auf localhost oder stellen Sie einen Reverse-Proxy davor, der das tut, und geben Sie ihm einen eigenen Namensraum.

Ein Setup für ein Team wählen

Die richtigen Flags hängen davon ab, wofür jeder Agent da ist. Jede Option unten ist ein Kommandozeilen-Flag. --read-only und --namespace haben außerdem Umgebungsvariablen, HOTKV_MCP_READ_ONLY und HOTKV_MCP_NAMESPACE.

Beginnen Sie mit der restriktivsten Zeile, die ihren Zweck erfüllt. Den Zugriff später zu erweitern ist leicht, zurückzunehmen, was ein Agent schon geschrieben hat, schwer.

Eine erste Sitzung, Schritt für Schritt

Ein kurzer Test zeigt, was die Schutzmaßnahmen bewirken, bevor Sie dem Server echte Notizen anvertrauen. Verwenden Sie einen Wegwerf-Namensraum und einen lokalen HotKV-Server, der für die KI-Engines lizenziert ist, denn ohne diese Lizenz funktionieren die Gedächtniswerkzeuge nicht.

1. Mit einem Namensraum verbinden. Führen Sie claude mcp add hotkv -- uvx hotkv-mcp --url hotkv://localhost:6379 --namespace trial aus.
2. Die Grenzen prüfen. Bitten Sie den Assistenten, server_info aufzurufen und den Namensraum zu nennen und ob der Server schreibgeschützt ist. Er sollte trial sagen und nicht schreibgeschützt.
3. Eine Notiz speichern. Bitten Sie ihn, sich zu merken, dass die Staging-Site unter einer bestimmten Adresse liegt, in einer nach der Site benannten Notiz. Der Assistent ruft memory_set_note auf, und die Sitzung wird bei der ersten Nutzung angelegt.
4. In einem neuen Chat zurücklesen. Starten Sie ein frisches Gespräch und fragen Sie, welche Notizen es für diese Sitzung gibt. Er ruft memory_list_notes und memory_get_note auf, und die Notiz ist noch da.
5. Eine Entscheidung protokollieren. Bitten Sie ihn, eine Entscheidung im Ereignisprotokoll festzuhalten. Er ruft memory_log_event auf, und memory_query_events bringt sie später zurück.
6. Den Schreibzugriff entziehen. Entfernen Sie den alten Eintrag, verbinden Sie sich neu mit --read-only und wiederholen Sie Schritt 4. Das Lesen funktioniert weiterhin, und die schreibenden Werkzeuge werden nicht mehr angeboten.

Verhält sich Schritt 6 wie beschrieben, haben Sie die beiden wichtigsten Kontrollen gesehen, den Namensraum und den Nur-Lese-Modus.

Behandeln Sie alles, was der Assistent speichert, beim Zurücklesen als nicht vertrauenswürdigen Text, wie der Artikel zum Gedächtnis unter gespeicherten Text als nicht vertrauenswürdig behandeln erklärt. Notizen, die aus Webseiten geschrieben wurden, können Anweisungen enthalten.

Fehlersuche

• „This HotKV server is not licensed for that feature.“ Die Werkzeuge für Gedächtnis, Prompts und Dokumentensuche brauchen eine HotKV-Lizenz, die die KI-Engines einschließt. Die Werkzeuge für Schlüssel, Hashes und Listen funktionieren auch ohne eine.
• Die Verbindung schlägt fehl. Prüfen Sie das URL-Schema. hotkv://, hotkvs:// (TLS), redis:// und rediss:// funktionieren alle, und ein Passwort steht in der URL als hotkv://:password@host:6379.
• Ein Wert kommt abgeschnitten zurück. Das Ergebnis wird als abgeschnitten markiert, wenn es --max-value-bytes überschreitet. Erhöhen Sie das Limit oder speichern Sie kleinere Werte.
• Ein Schreibwerkzeug fehlt. Suchen Sie nach --read-only in den Argumenten des Servers oder nach HOTKV_MCP_READ_ONLY in seiner Umgebung.
• Der Assistent findet einen früher gespeicherten Namen nicht. Prüfen Sie, ob er denselben Sitzungs- oder Agentennamen verwendet hat und ob der Server mit demselben Namensraum läuft wie zuvor.
• uvx wird nicht gefunden. Installieren Sie uv, oder installieren Sie das Paket mit pip und starten Sie hotkv-mcp direkt.

Häufig gestellte Fragen