agentx402-ai/agentkv

AgentKV-Fähigkeit (Skill)

AgentKV ist ein agenten-nativer Key-Value-Speicher. Du hast ein AgentKV-Konto, das auf eine von zwei Arten verwaltet wird (automatisch vom Client erkannt) – gleiche Daten, gleiche Credits, gleiche Zero-Knowledge-Verschlüsselung:

• Wallet als Schlüssel (Standard): Ein signierbares Wallet ist das Konto. Seine Adresse ist der Namensraum und sein Schlüssel leitet den AES-Schlüssel ab. AgentKV erstellt bei der ersten Nutzung automatisch ein Wallet – keine Konten, keine API-Schlüssel, keine Anmeldung.
• Konto-Schlüssel: Für ein verwaltetes Wallet, das nicht signieren kann (z. B. awal), dient ein undurchsichtiges ak_… Bearer-Token als Identität + Namensraum und ein lokaler Verschlüsselungsschlüssel verschlüsselt – entkoppelt vom zahlenden Wallet, sodass jedes signierende Wallet das Konto aufladen kann.

Werte werden clientseitig (AES-256-GCM) verschlüsselt, bevor sie den Server erreichen – der Server ist also Zero-Knowledge. Die Speicherung kostet echte USDC auf Base (Mainnet) oder Base Sepolia (Testnetz), abgerechnet pro Operation über das x402-Protokoll.

Voraussetzung: @agentkv/cli muss auf npm veröffentlicht und über npx @agentkv/cli auflösbar sein. Zum Zeitpunkt dieser Erstellung ist das Paket noch nicht veröffentlicht – dieses Plugin ist das Artefakt, das auf diesen Veröffentlichungsschritt wartet.

---

Wann AgentKV verwenden

Verwende AgentKV, wenn du Folgendes benötigst:

• Beständiges sitzungsübergreifendes Gedächtnis – Fakten, Präferenzen, Zusammenfassungen oder Aufgabenstatus, die auch nach Ende der aktuellen Sitzung erhalten bleiben müssen.
• Geheime Speicherung und Nutzung – API-Schlüssel, Token oder Anmeldedaten. Der Server sieht nur Chiffretext (Zero-Knowledge). ⚠️ Bei einfachem agentkv_set/agentkv_get wird der Wert durch den Modellkontext dieses Agents geleitet; für echte Geheimnisse verwende die geheimnissicheren Tools (agentkv_set_from_env/_from_file zum Speichern, agentkv_get_to_file/agentkv_run_with_secret zur Nutzung), sodass der Klartext niemals in eine Modellrunde gelangt. Siehe Geheimnisse weiter unten.
• Gemeinsamer Flottenzustand – mehrere Agent-Instanzen, die ein einzelnes Wallet gemeinsam nutzen, können sich über einen gemeinsamen Namensraum koordinieren (z. B. eine Job-Warteschlange, eine Sperre, ein gemeinsamer Zähler).
• TTL-begrenzter temporärer Zustand – temporäre Werte (z. B. eine Nonce, ein Entwurf) mit automatischem Ablauf, sodass du nie manuell aufräumen musst.

Verwende AgentKV NICHT für:

• Große Binär-Blobs (maximale Wertgröße beträgt 256 KB).
• Kostenlose, Null-Kosten-Operationen in einem budgetbewussten Kontext – jede set- und get-Operation kostet USDC; überprüfe zuerst das Ausgabenlimit.
• Als Ersatz für eine richtige Datenbank in einer benutzergerichteten Anwendung (es wurde für Agent-Workloads entwickelt, nicht für datenbankintensive Web-Apps).

---

Verfügbare MCP-Tools

Der agentkv MCP-Server stellt zwölf Tools bereit – acht Kern-Tools plus vier geheimnissichere Tools, deren Klartext niemals in den Modellkontext gelangt (siehe Geheimnisse weiter unten):

Tool	Beschreibung	Kosten
agentkv_set	Schreibt einen verschlüsselten Wert unter einem Schlüssel. Optional mit TTL (Tage).	~0,005 USDC
agentkv_get	Liest und entschlüsselt einen Wert anhand des Schlüssels. Gleitende TTL setzt das Ablaufdatum standardmäßig zurück.	~0,003 USDC
agentkv_delete	Löscht einen Schlüssel sofort.	Kostenlos
agentkv_deposit	Zahlt USDC-Credits auf den Namensraum des Wallets ein, um Operationen vorzufinanzieren. Im Konto-Schlüssel-Modus abgelehnt (ein verwaltetes Konto hat kein Wallet – einzahlen über <endpoint>/account/deposit).	USDC-Kauf
agentkv_balance	Prüft den aktuellen USDC-Credit-Saldo für den Wallet-Namensraum.	Kostenlos
agentkv_wallet_address	Gibt die Wallet-Adresse (Namensraumkennung) zurück. Nur zur Information.	Kostenlos
agentkv_fund	Gibt eine Karte→USDC-Onramp-URL zurück, die USDC an das Wallet auf Base liefert. Erstellt nur eine URL – keine Zahlung erfolgt. Im Konto-Schlüssel-Modus abgelehnt (kein Wallet, um USDC zu kaufen).	Kostenlos
agentkv_list_keys	Listet die gespeicherten Schlüssel dieses Wallets auf – die echten SchlüsselNAMEN, lokal entschlüsselt; der Server sieht nur undurchsichtige Digests. Paginiert.	Kostenlos
agentkv_set_from_env	Speichert ein Geheimnis, das aus einer lokalen Umgebungsvariable gelesen wird (übergib den NAMEN). Der Wert gelangt niemals in den Modellkontext.	~0,005 USDC
agentkv_set_from_file	Speichert ein Geheimnis, das aus einer lokalen Datei gelesen wird (übergib den PFAD). Der Inhalt gelangt niemals in den Modellkontext.	~0,005 USDC
agentkv_get_to_file	Entschlüsselt einen Wert in eine lokale Datei; gibt { gefunden, pfad, bytes } zurück – niemals den Wert selbst.	~0,003 USDC
agentkv_run_with_secret	Führt einen Befehl aus, wobei das Geheimnis nur in der Umgebung des Kindprozesses injiziert wird; gibt die Ausgabe des Befehls zurück, niemals das Geheimnis.	~0,003 USDC

Preise & Einzahlungen: Pay-as-you-go kostet ~0,005 USDC pro agentkv_set und ~0,003 USDC pro agentkv_get. Vorausbezahlte Credits kosten etwa 1/10 davon (≈ 0,0005 USDC pro Set, ≈ 0,0003 USDC pro Get). agentkv_deposit erfordert ein Minimum von 1,00 USDC und schreibt den Namensraum zum ermäßigten Credit-Satz gut.

---

Geheimnisse – den Wert aus dem Modellkontext heraushalten

agentkv_set und agentkv_get leiten den Wert durch den eigenen Modellkontext dieses Agents (es ist ein Tool-Argument beim Schreiben, ein Tool-Ergebnis beim Lesen). Clientseitige Verschlüsselung macht Werte gegenüber dem Server Zero-Knowledge – sie verbirgt sie nicht vor dem Agenten. Einfaches set/get ist also in Ordnung für nicht geheime Erinnerungen (Pläne, Zusammenfassungen, Präferenzen), aber für echte Anmeldedaten verwende die geheimnissicheren Tools, damit der Klartext niemals in eine Modellrunde gelangt:

• Speichern: agentkv_set_from_env (übergib einen Umgebungsvariablen-NAMEN) oder agentkv_set_from_file (übergib einen PFAD). Der Server liest den Wert lokal, verschlüsselt und speichert ihn.
• Verwenden: agentkv_run_with_secret (führt einen Befehl aus, wobei das Geheimnis nur in der Umgebung des Kindprozesses vorhanden ist, und gibt die Ausgabe des Befehls zurück) oder agentkv_get_to_file (schreibt den entschlüsselten Wert in eine lokale Datei und gibt den Pfad zurück – lösche sie nach Gebrauch).

Restrisiko: Das Geheimnis erscheint kurzzeitig in einer lokalen Datei oder in der Umgebung eines Kindprozesses – lokal und flüchtig, niemals an einen Modellanbieter gesendet oder in den Konversationsverlauf geschrieben. agentkv_run_with_secret (keine Datei auf der Festplatte) ist die strengste Lösung.

---

Einmalige Einrichtung

Installiere das Plugin aus dem Claude Code Marketplace – die genauen /plugin marketplace add- und /plugin install-Befehle findest du in der README.md des Plugins (plugin/README.md). Nach der Installation:

1. Anmeldedaten (bei der Installation eingegeben, nicht über die Shell-Umgebung)

Wenn das Plugin installiert wird, fragt Claude Code danach und leitet sie an den MCP-Server weiter (der private Schlüssel wird maskiert und in deiner OS-Keychain gespeichert – niemals auf die Festplatte geschrieben):

Konfiguration	Erforderlich	Beschreibung
Wallet Private Key	Nein	Optional – leer lassen, dann erstellt und verwaltet AgentKV bei der ersten Nutzung ein lokales Wallet (dann aufladen und sichern). Um dein eigenes zu verwenden: ein EVM-Private-Key (hex), das Wallet, das zahlt und den Namensraum besitzt.
AgentKV-Endpunkt	Nein	Die gehostete AgentKV-API; Standard ist https://api.agentx402.ai.
Netzwerk	Nein	eip155:8453 (Base Mainnet, Standard) oder eip155:84532 (Base Sepolia Testnetz).
Verschlüsselungsschlüssel	Nein	Überschreibt den abgeleiteten AES-Schlüssel (fortgeschritten; Standard ist HKDF aus dem Private Key).
Max. Ausgabe pro Operation (USD)	Nein	Lehnt jede einzelne Operation ab, die mehr kosten würde; leer = kein Limit pro Operation.
Max. Sitzungsausgabe (USD)	Nein	Lehnt Operationen ab, sobald die kumulative Sitzungsausgabe diesen Wert überschreitet; leer = kein Limit.

Führe später /plugin aus, um diese Werte zu ändern. Überprüfe, ob der Server mit /mcp geladen wurde (du solltest den agentkv-Server und seine zwölf Tools sehen).

Um mit einer Karte anstelle eines vorhandenen USDC-Guthabens aufzuladen, gibt das agentkv_fund-Tool eine Coinbase-Onramp-URL zurück – konfiguriere sie, indem du AGENTKV_ONRAMP_APP_ID (eine öffentliche CDP-Projekt-ID) auf dem Server setzt und optional AGENTKV_ONRAMP_PROVIDER, um den Anbieter zu wechseln.

2. Namensraum aufladen

Lies deine Wallet-Adresse mit agentkv_wallet_address aus, sende USDC an diese Adresse auf Base (oder rufe agentkv_fund für eine Karte→USDC-Onramp-URL auf, die USDC an diese Adresse liefert), rufe dann agentkv_deposit mit einem Betrag (Minimum 1 USDC) auf, um den Namensraum gutzuschreiben. Lese- und Schreiboperationen werden dann automatisch aus den Credits bezahlt.

Konto-Schlüssel-Modus (verwaltete Wallets / awal)

Ein verwaltetes Wallet, das nicht signieren kann, verwendet den Konto-Schlüssel-Modus anstelle eines Wallets. Außerhalb des Plugins erstellt und finanziert die CLI ein Konto:

agentkv account new        # erstellt ak_… + einen lokalen Verschlüsselungsschlüssel (gespeichert 0600) – SICHERE SIE, nicht wiederherstellbar
# Finanziere es von einem BELIEBIGEN signierenden Wallet (eine echte Einzahlung ≥1 USDC erstellt das Konto bei der ersten Einzahlung):
awal x402 pay https://api.agentx402.ai/account/deposit --headers '{"Authorization":"Bearer ak_..."}'

Setze dann AGENTKV_ACCOUNT_KEY=ak_… und AGENTKV_ENCRYPTION_KEY=0x… (den lokalen AES-Schlüssel – erforderlich im Konto-Modus, da es kein Wallet gibt, um einen abzuleiten). Das Konto ist der Namensraum; standardmäßig tragen Lese-/Schreiboperationen nur das Bearer-Token und belasten vorausbezahlte Credits – keine Signatur pro Operation. In jedem Fall bleibt es gegenüber dem Server Zero-Knowledge. Jedes signierende Wallet kann dasselbe Konto aufladen.

Mit zusätzlich gesetztem AGENTKV_TOPOFF=awal heilen sich unzureichende Credits selbst – kein Handlungsbedarf, die CLI/MCP-Sitzung bezahlt ihre eigene Nachladung über awal und fährt fort. Ohne diese Einstellung führe bei einem Fehler wegen unzureichender Credits awal x402 pay <endpoint>/account/deposit --headers '{"Authorization":"Bearer <ak>"}' aus und wiederhole den Vorgang. Alternativ setze AGENTKV_INLINE=awal, um pro Operation inline zu bezahlen: Jede Anfrage trägt eine Zahlungssignatur zusammen mit dem Bearer-Token und wird sofort on-chain abgerechnet, sodass vorausbezahlte Credits überhaupt nicht erforderlich sind.

---

Ausgabenlimit-Bewusstsein

Jeder agentkv_set-, agentkv_get- und agentkv_deposit-Aufruf kostet echte USDC (agentkv_delete, agentkv_balance, agentkv_wallet_address, agentkv_fund und agentkv_list_keys sind kostenlos). Bevor du eine Schleife oder Massenoperation startest:

1. Rufe agentkv_balance auf, um ausreichende Credits zu bestätigen.
2. Setze eine Max. Ausgabe pro Operation (USD) und/oder Max. Sitzungsausgabe (USD)-Obergrenze in der Plugin-Konfiguration (führe /plugin aus, um sie zu bearbeiten).
3. Wenn ein Toolaufruf einen 402 Payment Required-Fehler zurückgibt und kein Ausgabenbudget mehr übrig ist, pausiere und melde dies dem Benutzer, anstatt blind neu zu versuchen.

Der Server gibt eine PAYMENT-REQUIRED-Challenge zurück, wenn die Credits erschöpft sind; die CLI verarbeitet die x402-Zahlung automatisch innerhalb des Ausgabenlimits.

---

Muster für gemeinsamen Flottenzustand

Wenn mehrere Agents einen einzelnen AGENTKV_PRIVATE_KEY gemeinsam nutzen (gleiches Wallet = gleicher Namensraum), können sie sich über bekannte Schlüssel koordinieren:

fleet:lock:<task-id>     # verteilte Sperre (setzen mit kurzer TTL)
fleet:queue              # serialisierte Job-Liste
fleet:result:<task-id>   # Ausgabe einer abgeschlossenen Teilaufgabe

Verwende kurze TTLs für Sperren, um veraltete Halte zu verhindern, falls ein Agent abstürzt.

---

Schlüsselbenennungskonventionen

• Verwende : als Trennzeichen: session:<id>:summary, secret:github-token, prefs:language. Speichere/lies secret:*-Schlüssel mit den geheimnissicheren Tools (agentkv_set_from_env/_from_file, agentkv_get_to_file/run_with_secret) – niemals einfaches set/get – damit die Anmeldedaten niemals in den Modellkontext gelangen.
• Stelle benutzerspezifischen Daten eine stabile Kennung voran: user:<handle>:....
• Verwende agentkv_wallet_address, um zu bestätigen, in welchem Namensraum du arbeitest, bevor du gemeinsamen Flottenzustand schreibst.