AgentKV – Mémoire persistante et sécurisée pour agents IA

Compétence AgentKV

AgentKV est un magasin clé-valeur natif pour agents. Vous détenez un compte AgentKV, géré de deux manières (détection automatique par le client) — mêmes données, mêmes crédits, même chiffrement zero-knowledge :

• Portefeuille comme clé (par défaut) : un portefeuille signataire est le compte. Son adresse est l'espace de noms et sa clé dérive la clé AES. AgentKV en provisionne automatiquement un lors de la première utilisation — pas de comptes, pas de clés API, pas d'inscription.
• Clé de compte : pour un portefeuille géré qui ne peut pas signer (ex. awal), un jeton opaque ak_… de type bearer sert d'identité + espace de noms et une clé de chiffrement locale chiffre les données — découplé du portefeuille payeur, donc tout portefeuille signataire peut approvisionner le compte.

Les valeurs sont chiffrées côté client (AES-256-GCM) avant d'atteindre le serveur, ce dernier n'a donc aucune connaissance des données. Le stockage coûte du USDC réel sur Base (mainnet) ou Base Sepolia (testnet), facturé par opération via le protocole x402.

Prérequis : @agentkv/cli doit être publié sur npm et résoluble via npx @agentkv/cli. À ce jour, le paquet n'est pas encore publié — ce plugin est l'artefact en attendant cette publication.

---

Quand utiliser AgentKV

Utilisez AgentKV quand vous avez besoin de :

• Mémoire persistante entre sessions — faits, préférences, résumés ou état de tâche qui doivent survivre à la fin de la session courante.
• Stockage et utilisation de secrets — clés API, jetons ou identifiants. Le serveur ne voit jamais que du texte chiffré (zero-knowledge). ⚠️ Les outils agentkv_set/agentkv_get classiques font transiter la valeur par le contexte du modèle de cet agent ; pour de vrais secrets, utilisez les outils secret-safe (agentkv_set_from_env/_from_file pour stocker, agentkv_get_to_file/agentkv_run_with_secret pour utiliser) afin que le texte en clair n'entre jamais dans un tour de modèle. Voir Secrets ci-dessous.
• État partagé entre flottes — plusieurs instances d'agents partageant un même portefeuille peuvent se coordonner via un espace de noms commun (ex. file d'attente de tâches, verrou, compteur partagé).
• État temporaire limité par TTL — valeurs éphémères (ex. nonce, brouillon) avec expiration automatique pour éviter tout nettoyage manuel.

N'utilisez PAS AgentKV pour :

• De gros blocs binaires (taille maximale de valeur : 256 Ko).
• Des opérations gratuites et sans coût dans un contexte sensible au budget — chaque set et get coûte du USDC ; vérifiez d'abord le plafond de dépenses.
• Remplacer une base de données classique dans une application orientée utilisateur (il est conçu pour les charges de travail d'agents, pas pour les applications web à haut débit).

---

Outils MCP disponibles

Le serveur MCP agentkv expose douze outils — huit de base, plus quatre outils secret-safe dont le texte en clair n'entre jamais dans le contexte du modèle (voir Secrets ci-dessous) :

Outil	Description	Coût
agentkv_set	Écrire une valeur chiffrée sous une clé. Accepte un TTL optionnel (en jours).	~0,005 USDC
agentkv_get	Lire et déchiffrer une valeur par clé. Le TTL glissant réinitialise l'expiration par défaut.	~0,003 USDC
agentkv_delete	Supprimer une clé immédiatement.	Gratuit
agentkv_deposit	Déposer des crédits USDC dans l'espace de noms du portefeuille pour préfinancer les opérations. Refusé en mode clé de compte (un compte géré n'a pas de portefeuille — financez-le via <endpoint>/account/deposit).	Achat USDC
agentkv_balance	Vérifier le solde actuel des crédits USDC pour l'espace de noms du portefeuille.	Gratuit
agentkv_wallet_address	Retourner l'adresse du portefeuille (identifiant d'espace de noms). Informationnel.	Gratuit
agentkv_fund	Retourner une URL d'achat USDC par carte qui livre du USDC au portefeuille sur Base. Construit une URL uniquement — aucun paiement n'est effectué. Refusé en mode clé de compte (pas de portefeuille pour acheter du USDC).	Gratuit
agentkv_list_keys	Lister les clés stockées de ce portefeuille — les VRAIS NOMS de clés, déchiffrés localement ; le serveur ne voit que des digestions opaques. Paginé.	Gratuit
agentkv_set_from_env	Stocker un secret lu depuis une variable d'environnement locale (passez le NOM). La valeur n'entre jamais dans le contexte du modèle.	~0,005 USDC
agentkv_set_from_file	Stocker un secret lu depuis un fichier local (passez le CHEMIN). Le contenu n'entre jamais dans le contexte du modèle.	~0,005 USDC
agentkv_get_to_file	Déchiffrer une valeur vers un fichier local ; retourne { found, path, bytes } — jamais la valeur.	~0,003 USDC
agentkv_run_with_secret	Exécuter une commande avec le secret injecté dans l'environnement du processus enfant uniquement ; retourne la sortie de la commande, jamais le secret.	~0,003 USDC

Tarifs et dépôts : le paiement à l'utilisation est d'environ 0,005 USDC par agentkv_set et 0,003 USDC par agentkv_get. Les crédits prépayés coûtent environ 1/10 de cela (≈ 0,0005 USDC par set, ≈ 0,0003 USDC par get). agentkv_deposit nécessite un minimum de 1,00 $ et crédite l'espace de noms au taux de crédit réduit.

---

Secrets — garder la valeur hors du contexte du modèle

Les outils agentkv_set et agentkv_get font transiter la valeur par le contexte du modèle de cet agent (c'est un argument d'outil en écriture, un résultat d'outil en lecture). Le chiffrement côté client rend les valeurs zero-knowledge pour le serveur — il ne les cache pas de l'agent. Donc les set/get classiques conviennent pour la mémoire non secrète (plans, résumés, préférences), mais pour de vrais identifiants, utilisez les outils secret-safe afin que le texte en clair n'entre jamais dans un tour de modèle :

• Stockage : agentkv_set_from_env (passez un NOM de variable d'environnement) ou agentkv_set_from_file (passez un CHEMIN). Le serveur lit la valeur localement, la chiffre et la stocke.
• Utilisation : agentkv_run_with_secret (exécute une commande avec le secret dans l'environnement du processus enfant uniquement et retourne la sortie de la commande) ou agentkv_get_to_file (écrit la valeur déchiffrée dans un fichier local et retourne le chemin — supprimez-le après usage).

Résiduel : le secret se matérialise brièvement dans un fichier local ou l'environnement d'un processus enfant — local et éphémère, jamais envoyé à un fournisseur de modèle ni écrit dans l'historique de conversation. agentkv_run_with_secret (aucun fichier sur le disque) est le plus strict.

---

Configuration unique

Installez le plugin depuis la marketplace de Claude Code — les commandes exactes /plugin marketplace add et /plugin install se trouvent dans le README.md du plugin (plugin/README.md). Après installation :

1. Identifiants (saisis lors de l'installation, pas via les variables d'environnement shell)

Lorsque le plugin est installé, Claude Code demande ces informations et les transmet au serveur MCP pour vous (la clé privée est masquée et stockée dans le trousseau de votre système d'exploitation — jamais écrite sur le disque) :

Configuration	Requis	Description
Clé privée du portefeuille	Non	Optionnel — laissez vide et AgentKV crée + gère un portefeuille local lors de la première utilisation (ensuite financez-le + sauvegardez-le). Pour utiliser le vôtre : une clé privée EVM (hexadécimale), le portefeuille qui paie et possède l'espace de noms.
Point de terminaison AgentKV	Non	L'API AgentKV hébergée ; par défaut https://api.agentx402.ai.
Réseau	Non	eip155:8453 (Base mainnet, par défaut) ou eip155:84532 (Base Sepolia testnet).
Clé de chiffrement	Non	Remplace la clé AES dérivée (avancé ; par défaut HKDF à partir de la clé privée).
Dépense maximale par opération (USD)	Non	Refuser toute opération unique qui coûterait plus que ce montant ; vide = pas de limite par opération.
Dépense maximale par session (USD)	Non	Refuser les opérations une fois que les dépenses cumulées de la session dépassent ce montant ; vide = pas de limite.

Réexécutez /plugin pour les modifier plus tard. Vérifiez que le serveur est chargé avec /mcp (vous devriez voir le serveur agentkv et ses douze outils).

Pour financer par carte plutôt qu'avec un solde USDC existant, l'outil agentkv_fund retourne une URL Coinbase onramp — configurez-la en définissant AGENTKV_ONRAMP_APP_ID (un ID de projet CDP public) sur le serveur, et optionnellement AGENTKV_ONRAMP_PROVIDER pour changer de fournisseur.

2. Financez l'espace de noms

Lisez l'adresse de votre portefeuille avec agentkv_wallet_address, envoyez du USDC sur Base à cette adresse (ou appelez agentkv_fund pour une URL d'achat par carte qui livre du USDC à cette adresse), puis appelez agentkv_deposit avec un montant (minimum 1 $) pour créditer l'espace de noms. Les lectures et écritures sont ensuite payées automatiquement à partir des crédits.

Mode clé de compte (portefeuilles gérés / awal)

Un portefeuille géré qui ne peut pas signer utilise le mode clé de compte au lieu d'un portefeuille. En dehors du plugin, la CLI crée et finance un compte :

agentkv account new        # crée ak_… + une clé de chiffrement locale (sauvegardée 0600) — SAUVEGARDEZ-LES, irrécupérables
# Financez-le à partir de TOUT portefeuille signataire (un dépôt réel ≥1$ crée le compte lors du premier dépôt) :
awal x402 pay https://api.agentx402.ai/account/deposit --headers '{"Authorization":"Bearer ak_..."}'

Définissez ensuite AGENTKV_ACCOUNT_KEY=ak_… et AGENTKV_ENCRYPTION_KEY=0x… (la clé AES locale — requise en mode compte, il n'y a pas de portefeuille pour en dériver une). Le compte est l'espace de noms ; par défaut, les lectures/écritures portent uniquement le jeton bearer et débitent les crédits prépayés — pas de signature par opération. Dans les deux cas, les données restent zero-knowledge pour le serveur. Tout portefeuille signataire peut approvisionner le même compte.

Avec AGENTKV_TOPOFF=awal également défini, les crédits insuffisants s'auto-réparent — aucune action requise, la session CLI/MCP paie son propre réapprovisionnement via awal et continue. Sans cela, en cas d'erreur de crédits insuffisants, exécutez awal x402 pay <endpoint>/account/deposit --headers '{"Authorization":"Bearer <ak>"}' et réessayez. Alternativement, définissez AGENTKV_INLINE=awal pour payer par opération en ligne : chaque requête porte une signature de paiement avec le jeton bearer et se règle immédiatement sur la chaîne, donc les crédits prépayés ne sont pas du tout nécessaires.

---

Sensibilisation au plafond de dépenses

Chaque appel à agentkv_set, agentkv_get et agentkv_deposit coûte du USDC réel (agentkv_delete, agentkv_balance, agentkv_wallet_address, agentkv_fund et agentkv_list_keys sont gratuits). Avant de lancer une boucle ou une opération groupée :

1. Appelez agentkv_balance pour confirmer un nombre suffisant de crédits.
2. Définissez un plafond de Dépense maximale par opération (USD) et/ou Dépense maximale par session (USD) dans la configuration du plugin (exécutez /plugin pour éditer).
3. Si un appel d'outil retourne une erreur 402 Payment Required et qu'il ne reste plus de budget, faites une pause et signalez-le à l'utilisateur plutôt que de réessayer aveuglément.

Le serveur retourne un défi PAYMENT-REQUIRED lorsque les crédits sont épuisés ; la CLI traite le paiement x402 automatiquement dans la limite du plafond de dépenses.

---

Modèle d'état partagé entre flottes

Lorsque plusieurs agents partagent une seule AGENTKV_PRIVATE_KEY (même portefeuille = même espace de noms), ils peuvent se coordonner via des clés bien connues :

fleet:lock:<task-id>     # verrou distribué (set avec un TTL court)
fleet:queue              # liste de tâches sérialisée
fleet:result:<task-id>   # sortie d'une sous-tâche terminée

Utilisez des TTL courts sur les verrous pour éviter les blocages obsolètes si un agent plante.

---

Conventions de nommage des clés

• Utilisez : comme séparateur : session:<id>:summary, secret:github-token, prefs:language. Stockez/lisez les clés secret:* avec les outils secret-safe (agentkv_set_from_env/_from_file, agentkv_get_to_file/run_with_secret) — jamais les outils set/get classiques — afin que l'identifiant n'entre jamais dans le contexte du modèle.
• Préfixez les données spécifiques à un utilisateur avec un identifiant stable : user:<handle>:....
• Utilisez agentkv_wallet_address pour confirmer dans quel espace de noms vous opérez avant d'écrire un état partagé entre flottes.