Server MCP untuk memori agen: hubungkan Claude Code ke HotKV

Server MCP adalah cara paling sederhana untuk memberi asisten AI memori yang bertahan lebih lama dari satu chat. Claude Code, Cursor, dan klien sejenis kehilangan konteks sebuah chat ketika chat itu berakhir. Memberi mereka akses database mentah untuk mengatasinya berisiko. hotkv-mcp adalah server MCP open source kami untuk HotKV. Ia memberi asisten sekumpulan tool tetap untuk catatan, riwayat percakapan, log peristiwa, template prompt, dan pencarian dokumen. Ia tidak menawarkan hal lain.

Singkatnya. hotkv-mcp adalah server MCP Apache-2.0 yang menghubungkan Claude Code, Cursor, VS Code, atau agen Anda sendiri ke server HotKV lewat 28 tool tetap. Tidak ada tool yang menjalankan perintah sembarang, sehingga asisten tidak dapat mengosongkan data atau mengubah konfigurasi. Mode baca-saja menghapus setiap tool penulisan, dan namespace membatasi agen pada satu prefiks kunci. Pasang dengan pip install hotkv-mcp atau jalankan dengan uvx.

Apa itu Model Context Protocol

Model Context Protocol, atau MCP, adalah standar terbuka untuk menghubungkan aplikasi AI ke sistem eksternal seperti sumber data, tool, dan alur kerja. Pengantar proyek ini membandingkannya dengan port USB-C untuk aplikasi AI. Dalam istilah MCP, aplikasi adalah klien, dan setiap sistem yang dihubungkannya diekspos oleh sebuah server.

Untuk memori, artinya asisten memanggil tool bernama, seperti tool yang menyimpan catatan. Server yang memutuskan apa yang boleh dilakukan tool itu. Model tidak pernah mendapat koneksi database sendiri.

Apa yang diekspos server MCP HotKV

Server membungkus memori agen, registri prompt, dan pencarian dokumen HotKV dalam 28 tool. Setiap tool menyatakan dalam anotasi MCP-nya apakah ia hanya membaca, menulis, atau menghapus. Klien kemudian dapat meminta persetujuan sebelum yang destruktif.

Tool memori dipetakan ke penyimpanan yang dijelaskan di memori agen AI, yaitu riwayat percakapan, catatan kerja, dan log peristiwa. Recall semantik dengan embedding tidak diekspos. rag_search mengurutkan berdasarkan relevansi kata kunci, jadi tidak memerlukannya.

Tool kunci, hash, dan list bekerja pada server HotKV mana pun. Tool memori, prompt, dan pencarian dokumen memakai mesin AI HotKV, yang memerlukan lisensi yang menyertakannya. Tanpa itu, tool tersebut mengembalikan pesan bahwa server tidak berlisensi untuk fitur itu. Tool kunci tetap berfungsi. Instance HotKV Cloud Performance dan Scale menyertakan mesin AI, seperti dijelaskan halaman AI.

Pasang dan hubungkan

Server memerlukan Python 3.10 atau lebih baru. Ia ditulis terhadap server HotKV 0.3.0 dan paket resmi hotkv-client, dan versi 1.0.0 ada di PyPI. Pasang dengan pip, atau jalankan tanpa memasang memakai uv.

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

Claude Code

Tambahkan dengan satu perintah. Tanda -- memisahkan opsi Claude Code sendiri dari perintah yang memulai server, seperti dijelaskan dokumentasi MCP Claude Code.

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

Cursor dan Claude Desktop

Klien yang membaca file mcpServers menerima server yang sama sebagai entri JSON. Simpan kata sandi di variabel lingkungan HOTKV_URL atau penyimpanan rahasia klien. Baris perintah terlihat oleh pengguna lain di mesin itu. Gunakan hotkvs:// untuk koneksi TLS.

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

Periksa bahwa ia bekerja

Jalankan claude mcp list untuk memastikan server terdaftar. Lalu minta asisten memanggil tool server_info. Ia mengembalikan versi HotKV dan penggunaan memori, plus jumlah kunci bila tidak ada namespace yang diatur. Ia juga melaporkan apakah server bersifat baca-saja dan namespace mana yang membatasinya. Itu memastikan pengaman Anda berlaku.

Jaga agen dalam batas yang aman

Model yang dapat memanggil tool juga dapat dibujuk untuk menyalahgunakannya, jadi batasan lebih penting daripada fitur.

Tanpa perintah sembarang

Tidak ada tool yang menjalankan perintah mentah. Asisten tidak dapat mengosongkan database atau mengubah konfigurasi server, karena tak satu pun dari 28 tool melakukan hal itu. Ia dapat membaca kunci apa pun yang dijangkau tool, itulah sebabnya namespace di bawah ini penting.

Mode baca-saja

--read-only menghapus setiap tool yang menulis, termasuk set, delete, hash_set, list_push, tool memori yang menambah atau membersihkan, prompt_save, rag_create, dan rag_ingest. Agen bahkan tidak dapat melihatnya. Gunakan untuk asisten yang boleh berkonsultasi dengan memori tetapi tidak pernah mengubahnya.

Namespace dan batas ukuran

--namespace PREFIX menyimpan semuanya di bawah prefiks itu. Agen tidak pernah melihat prefiksnya dan tidak dapat menjangkau nama lain. Beri setiap agen prefiks yang bukan awal dari prefiks lain. Gunakan agent-a dan agent-b, bukan agent dan agent:b, atau yang lebih pendek dapat menjangkau nama yang lebih panjang.

Hasil juga dibatasi. --max-value-bytes memotong nilai yang panjang dan menandainya sebagai terpotong, dengan default 65.536 byte. --max-items membatasi berapa banyak kunci, item list, atau hit yang dikembalikan sebuah panggilan, 200 secara default. Satu nilai yang sangat besar karenanya tidak dapat membanjiri konteks model. Membaca seluruh hash tidak dibatasi jumlah itemnya, jadi jauhkan hash besar dari namespace agen.

Transport HTTP tidak memiliki login

Transport stdio default dijalankan oleh klien sebagai subproses. Untuk penggunaan bersama, Anda dapat menjalankan hotkv-mcp --transport streamable-http, yang mendengarkan di 127.0.0.1:8000 pada /mcp. Ia tidak mengautentikasi pemanggil. Biarkan di localhost atau taruh di belakang reverse proxy yang melakukannya, dan beri namespace sendiri.

Memilih pengaturan untuk sebuah tim

Flag yang tepat bergantung pada fungsi setiap agen. Setiap opsi di bawah ini adalah flag baris perintah. --read-only dan --namespace juga memiliki variabel lingkungan, HOTKV_MCP_READ_ONLY dan HOTKV_MCP_NAMESPACE.

Mulailah dari baris yang paling terbatas yang menyelesaikan pekerjaan. Mudah memperluas akses nanti, dan sulit mengambil kembali apa yang sudah ditulis agen.

Sesi pertama, langkah demi langkah

Uji coba singkat menunjukkan apa yang dilakukan pengaman sebelum Anda mempercayakan catatan sungguhan kepada server. Gunakan namespace sekali pakai dan server HotKV lokal yang berlisensi untuk mesin AI, karena tool memori tidak bekerja tanpa lisensi itu.

1. Hubungkan dengan namespace. Jalankan claude mcp add hotkv -- uvx hotkv-mcp --url hotkv://localhost:6379 --namespace trial.
2. Periksa batasannya. Minta asisten memanggil server_info dan melaporkan namespace serta apakah server baca-saja. Seharusnya ia menjawab trial dan bukan baca-saja.
3. Simpan catatan. Minta ia mengingat bahwa situs staging berada di alamat tertentu, di bawah catatan yang dinamai menurut situs itu. Asisten memanggil memory_set_note, dan sesi dibuat pada pemakaian pertama.
4. Baca kembali di chat baru. Mulai percakapan baru dan tanyakan catatan apa yang ada untuk sesi itu. Ia memanggil memory_list_notes dan memory_get_note, dan catatannya masih ada.
5. Catat sebuah keputusan. Minta ia merekam keputusan di log peristiwa. Ia memanggil memory_log_event, dan memory_query_events mengembalikannya nanti.
6. Cabut akses tulisnya. Hapus entri lama, hubungkan kembali dengan --read-only, dan ulangi langkah 4. Pembacaan tetap bekerja, dan tool yang menulis tidak lagi ditawarkan.

Jika langkah 6 berperilaku seperti yang dijelaskan, Anda telah melihat dua kontrol yang paling penting, namespace dan mode baca-saja.

Perlakukan apa pun yang disimpan asisten sebagai teks tidak tepercaya ketika dibaca kembali, seperti dijelaskan artikel memori dalam memperlakukan teks tersimpan sebagai tidak tepercaya. Catatan yang ditulis dari halaman web dapat membawa instruksi.

Pemecahan masalah

• "This HotKV server is not licensed for that feature." Tool memori, prompt, dan pencarian dokumen memerlukan lisensi HotKV yang menyertakan mesin AI. Tool kunci, hash, dan list tetap bekerja tanpanya.
• Koneksi gagal. Periksa skema URL. hotkv://, hotkvs:// (TLS), redis://, dan rediss:// semuanya bekerja, dan kata sandi dimasukkan di URL sebagai hotkv://:password@host:6379.
• Sebuah nilai kembali terpotong. Hasil ditandai terpotong ketika melewati --max-value-bytes. Naikkan batasnya atau simpan nilai yang lebih kecil.
• Tool penulisan tidak ada. Cari --read-only di argumen server atau HOTKV_MCP_READ_ONLY di lingkungannya.
• Asisten tidak dapat menemukan nama yang disimpannya sebelumnya. Periksa bahwa ia memakai nama sesi atau agen yang sama, dan bahwa server berjalan dengan namespace yang sama seperti sebelumnya.
• uvx tidak ditemukan. Pasang uv, atau pasang paketnya dengan pip dan jalankan hotkv-mcp langsung.

Pertanyaan yang sering diajukan