Server MCP pentru memoria agenților: conectați Claude Code la HotKV

Un server MCP este cea mai simplă cale de a oferi unui asistent IA o memorie care durează mai mult decât un singur chat. Claude Code, Cursor și clienții similari pierd contextul unui chat când acesta se încheie. Să le dați acces direct la baza de date pentru a repara asta este riscant. hotkv-mcp este serverul nostru MCP open source pentru HotKV. Oferă unui asistent un set fix de unelte pentru note, istoricul conversației, un jurnal de evenimente, șabloane de prompturi și căutare în documente. Nu oferă nimic altceva.

Pe scurt. hotkv-mcp este un server MCP Apache-2.0 care conectează Claude Code, Cursor, VS Code sau propriul agent la un server HotKV prin 28 de unelte fixe. Nu există nicio unealtă care să ruleze o comandă arbitrară, deci asistentul nu poate șterge date sau schimba configurația. Un mod numai-citire elimină fiecare unealtă de scriere, iar un spațiu de nume limitează agentul la un singur prefix de chei. Instalați-l cu pip install hotkv-mcp sau rulați-l cu uvx.

Ce este Model Context Protocol

Model Context Protocol, sau MCP, este un standard deschis pentru conectarea aplicațiilor IA la sisteme externe, precum surse de date, unelte și fluxuri de lucru. Introducerea proiectului îl compară cu un port USB-C pentru aplicațiile IA. În termeni MCP, aplicația este clientul, iar fiecare sistem la care se conectează este expus de un server.

Pentru memorie, asta înseamnă că asistentul apelează o unealtă cu nume, de exemplu una care salvează o notă. Serverul decide ce are voie să facă acea unealtă. Modelul nu primește niciodată o conexiune proprie la baza de date.

Ce expune serverul MCP HotKV

Serverul învelește memoria agenților din HotKV, registrul de prompturi și căutarea în documente în 28 de unelte. Fiecare unealtă declară în adnotările ei MCP dacă doar citește, scrie sau șterge. Un client poate atunci să ceară aprobare înainte de cele distructive.

Uneltele de memorie corespund stocurilor descrise în memoria agenților IA, adică istoricul conversației, notele de lucru și jurnalul de evenimente. Regăsirea semantică prin embedding nu este expusă. rag_search clasifică după relevanța cuvintelor-cheie, deci nu are nevoie de ea.

Uneltele pentru chei, hash-uri și liste funcționează cu orice server HotKV. Uneltele de memorie, de prompturi și de căutare în documente folosesc motoarele IA ale HotKV, care cer o licență ce le include. Fără ea, acele unelte returnează un mesaj că serverul nu este licențiat pentru funcție. Uneltele pentru chei continuă să funcționeze. Instanțele HotKV Cloud Performance și Scale includ motoarele IA, așa cum descrie pagina IA.

Instalare și conectare

Serverul cere Python 3.10 sau mai nou. A fost scris pentru serverul HotKV 0.3.0 și pachetul oficial hotkv-client, iar versiunea 1.0.0 se află pe PyPI. Instalați-l cu pip sau rulați-l fără instalare cu uv.

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

Claude Code

Adăugați-l cu o singură comandă. -- separă opțiunile proprii ale lui Claude Code de comanda care pornește serverul, așa cum descrie documentația MCP din Claude Code.

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

Cursor și Claude Desktop

Clienții care citesc un fișier mcpServers preiau același server ca intrare JSON. Țineți parola în variabila de mediu HOTKV_URL sau în depozitul de secrete al clientului. O linie de comandă este vizibilă altor utilizatori ai mașinii. Folosiți hotkvs:// pentru o conexiune TLS.

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

Verificați că funcționează

Rulați claude mcp list ca să confirmați că serverul este înregistrat. Apoi cereți asistentului să apeleze unealta server_info. Ea returnează versiunea HotKV și consumul de memorie, plus numărul de chei când nu este setat niciun spațiu de nume. Raportează și dacă serverul este numai-citire și la ce spațiu de nume este limitat. Asta confirmă că măsurile dvs. de protecție au intrat în vigoare.

Țineți agentul în limite sigure

Un model care poate apela unelte poate fi convins și să le folosească greșit, deci limitele contează mai mult decât funcțiile.

Fără comenzi arbitrare

Nu există nicio unealtă care să ruleze o comandă brută. Asistentul nu poate goli o bază de date și nu poate schimba configurația serverului, pentru că niciuna dintre cele 28 de unelte nu face asta. Poate citi orice cheie la care ajung uneltele, motiv pentru care spațiul de nume de mai jos contează.

Mod numai-citire

--read-only elimină fiecare unealtă care scrie, inclusiv set, delete, hash_set, list_push, uneltele de memorie care adaugă sau șterg, prompt_save, rag_create și rag_ingest. Agentul nici măcar nu le vede. Folosiți-l pentru asistenți care ar trebui să consulte memoria, dar niciodată să o schimbe.

Spații de nume și plafoane de dimensiune

--namespace PREFIX stochează totul sub acel prefix. Agentul nu vede niciodată prefixul și nu poate ajunge la alte nume. Dați fiecărui agent un prefix care nu este începutul altuia. Folosiți agent-a și agent-b, nu agent și agent:b, altfel cel mai scurt poate ajunge la numele celui mai lung.

Și rezultatele sunt plafonate. --max-value-bytes taie valorile lungi și le marchează ca trunchiate, cu o valoare implicită de 65.536 de octeți. --max-items limitează câte chei, elemente de listă sau rezultate returnează un apel, 200 implicit. O singură valoare uriașă nu poate deci să inunde contextul modelului. Citirea unui hash întreg nu este plafonată pe elemente, deci țineți hash-urile mari în afara spațiului de nume al unui agent.

Transportul HTTP nu are autentificare

Transportul stdio implicit este pornit de client ca subproces. Pentru utilizare partajată puteți rula hotkv-mcp --transport streamable-http, care ascultă pe 127.0.0.1:8000 la /mcp. Nu autentifică apelanții. Țineți-l pe localhost sau puneți-l în spatele unui reverse proxy care autentifică și dați-i propriul spațiu de nume.

Alegerea unei configurații pentru o echipă

Flagurile potrivite depind de scopul fiecărui agent. Fiecare opțiune de mai jos este un flag de linie de comandă. --read-only și --namespace au și variabile de mediu, HOTKV_MCP_READ_ONLY și HOTKV_MCP_NAMESPACE.

Porniți de la rândul cel mai restrictiv care face treaba. Este ușor să lărgiți accesul mai târziu și greu să luați înapoi ce a scris deja un agent.

O primă sesiune, pas cu pas

O probă scurtă arată ce fac măsurile de protecție, înainte să încredințați serverului note reale. Folosiți un spațiu de nume de unică folosință și un server HotKV local, licențiat pentru motoarele IA, pentru că uneltele de memorie nu funcționează fără acea licență.

1. Conectați-vă cu un spațiu de nume. Rulați claude mcp add hotkv -- uvx hotkv-mcp --url hotkv://localhost:6379 --namespace trial.
2. Verificați limitele. Cereți asistentului să apeleze server_info și să raporteze spațiul de nume și dacă serverul este numai-citire. Ar trebui să spună trial și nu numai-citire.
3. Salvați o notă. Cereți-i să rețină că site-ul de staging se află la o anumită adresă, sub o notă numită după site. Asistentul apelează memory_set_note, iar sesiunea este creată la prima utilizare.
4. Citiți-o într-un chat nou. Începeți o conversație nouă și întrebați ce note există pentru acea sesiune. Apelează memory_list_notes și memory_get_note, iar nota este încă acolo.
5. Înregistrați o decizie. Cereți-i să noteze o decizie în jurnalul de evenimente. Apelează memory_log_event, iar memory_query_events o aduce înapoi mai târziu.
6. Eliminați accesul de scriere. Eliminați intrarea veche, reconectați-vă cu --read-only și repetați pasul 4. Citirea funcționează în continuare, iar uneltele care scriu nu mai sunt oferite.

Dacă pasul 6 se comportă așa cum este descris, ați văzut cele două controale care contează cel mai mult, spațiul de nume și modul numai-citire.

Tratați tot ce stochează asistentul ca text nesigur atunci când este citit înapoi, așa cum explică articolul despre memorie în tratarea textului stocat ca nesigur. Notele scrise din pagini web pot purta instrucțiuni.

Depanare

• „This HotKV server is not licensed for that feature.” Uneltele de memorie, de prompturi și de căutare în documente cer o licență HotKV care include motoarele IA. Uneltele pentru chei, hash-uri și liste continuă să funcționeze fără ea.
• Conexiunea eșuează. Verificați schema URL-ului. hotkv://, hotkvs:// (TLS), redis:// și rediss:// funcționează toate, iar parola se pune în URL ca hotkv://:password@host:6379.
• O valoare vine tăiată. Rezultatul este marcat ca trunchiat când depășește --max-value-bytes. Măriți limita sau stocați valori mai mici.
• Lipsește o unealtă de scriere. Căutați --read-only în argumentele serverului sau HOTKV_MCP_READ_ONLY în mediul lui.
• Asistentul nu găsește un nume salvat mai devreme. Verificați că a folosit aceeași sesiune sau același nume de agent și că serverul rulează cu același spațiu de nume ca înainte.
• uvx nu este găsit. Instalați uv sau instalați pachetul cu pip și porniți direct hotkv-mcp.

Întrebări frecvente