Server MCP per la memoria degli agenti: collega Claude Code a HotKV

Un server MCP è il modo più semplice per dare a un assistente IA una memoria che duri più di una chat. Claude Code, Cursor e client simili perdono il contesto di una chat quando finisce. Dare loro un accesso diretto al database per rimediare è rischioso. hotkv-mcp è il nostro server MCP open source per HotKV. Offre a un assistente un insieme fisso di strumenti per appunti, cronologia delle conversazioni, registro degli eventi, template di prompt e ricerca nei documenti. Non offre nient'altro.

In breve. hotkv-mcp è un server MCP con licenza Apache-2.0 che collega Claude Code, Cursor, VS Code o il tuo agente a un server HotKV tramite 28 strumenti fissi. Non c'è nessuno strumento che esegua un comando arbitrario, quindi l'assistente non può svuotare i dati né cambiare la configurazione. Una modalità di sola lettura rimuove ogni strumento di scrittura e un namespace confina l'agente a un solo prefisso di chiavi. Installalo con pip install hotkv-mcp oppure eseguilo con uvx.

Che cos'è il Model Context Protocol

Il Model Context Protocol, o MCP, è uno standard aperto per collegare applicazioni di IA a sistemi esterni come fonti di dati, strumenti e flussi di lavoro. L'introduzione del progetto lo paragona a una porta USB-C per le applicazioni di IA. Nei termini di MCP l'applicazione è il client, e ogni sistema a cui si collega è esposto da un server.

Per la memoria questo significa che l'assistente chiama uno strumento con un nome, per esempio uno che salva un appunto. È il server a decidere che cosa quello strumento può fare. Il modello non ottiene mai una connessione al database tutta sua.

Cosa espone il server MCP di HotKV

Il server racchiude la memoria degli agenti, il registro dei prompt e la ricerca nei documenti di HotKV in 28 strumenti. Ogni strumento dichiara nelle sue annotazioni MCP se si limita a leggere, a scrivere o a eliminare. Un client può così chiedere conferma prima di quelli distruttivi.

Gli strumenti di memoria corrispondono agli archivi descritti in memoria degli agenti IA, cioè la cronologia delle conversazioni, gli appunti di lavoro e il registro degli eventi. Il richiamo semantico tramite embedding non è esposto. rag_search ordina per rilevanza delle parole chiave, quindi non ne ha bisogno.

Gli strumenti per chiavi, hash e liste funzionano con qualsiasi server HotKV. Gli strumenti di memoria, di prompt e di ricerca nei documenti usano i motori di IA di HotKV, che richiedono una licenza che li includa. Senza, quegli strumenti restituiscono un messaggio che dice che il server non ha la licenza per quella funzionalità. Gli strumenti per le chiavi continuano a funzionare. Le istanze HotKV Cloud Performance e Scale includono i motori di IA, come descrive la pagina sull'IA.

Installa e collega

Il server richiede Python 3.10 o successivo. È stato scritto per HotKV server 0.3.0 e per il pacchetto ufficiale hotkv-client, e la versione 1.0.0 è su PyPI. Installalo con pip, oppure eseguilo senza installare usando uv.

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

Claude Code

Aggiungilo con un solo comando. Il -- separa le opzioni proprie di Claude Code dal comando che avvia il server, come descrive la documentazione MCP di Claude Code.

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

Cursor e Claude Desktop

I client che leggono un file mcpServers accettano lo stesso server come voce JSON. Tieni la password nella variabile d'ambiente HOTKV_URL o nell'archivio dei segreti del client. Una riga di comando è visibile agli altri utenti della macchina. Usa hotkvs:// per una connessione TLS.

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

Verifica che funzioni

Esegui claude mcp list per confermare che il server sia registrato. Poi chiedi all'assistente di chiamare lo strumento server_info. Restituisce la versione di HotKV e l'uso di memoria, oltre al numero di chiavi quando non è impostato un namespace. Indica anche se il server è in sola lettura e a quale namespace è limitato. Questo conferma che le tue protezioni hanno avuto effetto.

Tieni l'agente entro limiti sicuri

Un modello che può chiamare strumenti può anche essere convinto a usarli male, quindi i limiti contano più delle funzionalità.

Nessun comando arbitrario

Non c'è nessuno strumento che esegua un comando grezzo. L'assistente non può svuotare un database né cambiare la configurazione del server, perché nessuno dei 28 strumenti lo fa. Può leggere qualsiasi chiave raggiunta dagli strumenti, ed è per questo che il namespace qui sotto conta.

Modalità di sola lettura

--read-only rimuove ogni strumento che scrive, tra cui set, delete, hash_set, list_push, gli strumenti di memoria che aggiungono o cancellano, prompt_save, rag_create e rag_ingest. L'agente non li vede nemmeno. Usala per gli assistenti che devono consultare la memoria senza mai modificarla.

Namespace e limiti di dimensione

--namespace PREFIX archivia tutto sotto quel prefisso. L'agente non vede mai il prefisso e non può raggiungere altri nomi. Dai a ogni agente un prefisso che non sia l'inizio di un altro. Usa agent-a e agent-b, non agent e agent:b, altrimenti quello più corto può raggiungere i nomi di quello più lungo.

Anche i risultati hanno un limite. --max-value-bytes taglia i valori lunghi e li segnala come troncati, con un valore predefinito di 65.536 byte. --max-items limita quante chiavi, elementi di lista o risultati restituisce una chiamata, 200 per impostazione predefinita. Un singolo valore enorme non può quindi inondare il contesto del modello. La lettura di un intero hash non ha un limite di elementi, quindi tieni gli hash grandi fuori dal namespace di un agente.

Il trasporto HTTP non ha login

Il trasporto stdio predefinito viene avviato dal client come sottoprocesso. Per l'uso condiviso puoi eseguire hotkv-mcp --transport streamable-http, che resta in ascolto su 127.0.0.1:8000 su /mcp. Non autentica i chiamanti. Tienilo su localhost oppure mettilo dietro un reverse proxy che lo faccia, e dagli un namespace tutto suo.

Scegliere una configurazione per un team

I flag giusti dipendono dallo scopo di ciascun agente. Ogni opzione qui sotto è un flag della riga di comando. --read-only e --namespace hanno anche variabili d'ambiente, HOTKV_MCP_READ_ONLY e HOTKV_MCP_NAMESPACE.

Parti dalla riga più restrittiva che svolge il compito. È facile ampliare l'accesso in seguito, ed è difficile riprendersi ciò che un agente ha già scritto.

Una prima sessione, passo per passo

Una breve prova mostra che cosa fanno le protezioni prima di affidare al server appunti veri. Usa un namespace temporaneo e un server HotKV locale con licenza per i motori di IA, perché gli strumenti di memoria non funzionano senza quella licenza.

1. Collegati con un namespace. Esegui claude mcp add hotkv -- uvx hotkv-mcp --url hotkv://localhost:6379 --namespace trial.
2. Controlla i limiti. Chiedi all'assistente di chiamare server_info e di indicare il namespace e se il server è in sola lettura. Dovrebbe rispondere trial e non in sola lettura.
3. Salva un appunto. Chiedigli di ricordare che il sito di staging si trova a un dato indirizzo, in un appunto con il nome del sito. L'assistente chiama memory_set_note, e la sessione viene creata al primo utilizzo.
4. Rileggilo in una nuova chat. Avvia una conversazione nuova e chiedi quali appunti esistono per quella sessione. Chiama memory_list_notes e memory_get_note, e l'appunto c'è ancora.
5. Registra una decisione. Chiedigli di annotare una decisione nel registro degli eventi. Chiama memory_log_event, e memory_query_events la riporta più tardi.
6. Togli l'accesso in scrittura. Rimuovi la vecchia voce, ricollegati con --read-only e ripeti il passo 4. La lettura funziona ancora e gli strumenti che scrivono non vengono più offerti.

Se il passo 6 si comporta come descritto, hai visto i due controlli che contano di più, il namespace e la modalità di sola lettura.

Tratta qualsiasi cosa l'assistente archivia come testo non attendibile quando viene riletta, come spiega l'articolo sulla memoria in trattare il testo archiviato come non attendibile. Gli appunti scritti a partire da pagine web possono contenere istruzioni.

Risoluzione dei problemi

• "This HotKV server is not licensed for that feature." Gli strumenti di memoria, di prompt e di ricerca nei documenti richiedono una licenza HotKV che includa i motori di IA. Gli strumenti per chiavi, hash e liste continuano a funzionare senza.
• La connessione non riesce. Controlla lo schema dell'URL. hotkv://, hotkvs:// (TLS), redis:// e rediss:// funzionano tutti, e una password va nell'URL come hotkv://:password@host:6379.
• Un valore torna tagliato. Il risultato viene segnalato come troncato quando supera --max-value-bytes. Alza il limite oppure archivia valori più piccoli.
• Manca uno strumento di scrittura. Cerca --read-only negli argomenti del server o HOTKV_MCP_READ_ONLY nel suo ambiente.
• L'assistente non trova un nome che aveva salvato prima. Controlla che abbia usato lo stesso nome di sessione o di agente e che il server sia in esecuzione con lo stesso namespace di prima.
• uvx non viene trovato. Installa uv, oppure installa il pacchetto con pip e avvia direttamente hotkv-mcp.

Domande frequenti