Serwer MCP dla pamięci agentów: połącz Claude Code z HotKV

Serwer MCP to najprostszy sposób, by dać asystentowi AI pamięć, która trwa dłużej niż jedna rozmowa. Claude Code, Cursor i podobni klienci tracą kontekst czatu, gdy ten się kończy. Danie im surowego dostępu do bazy danych, by to naprawić, jest ryzykowne. hotkv-mcp to nasz otwartoźródłowy serwer MCP dla HotKV. Daje asystentowi stały zestaw narzędzi do notatek, historii konwersacji, dziennika zdarzeń, szablonów promptów i wyszukiwania dokumentów. Nie oferuje niczego więcej.

W skrócie. hotkv-mcp to serwer MCP na licencji Apache-2.0, który łączy Claude Code, Cursor, VS Code lub Twojego własnego agenta z serwerem HotKV przez 28 stałych narzędzi. Nie ma narzędzia uruchamiającego dowolne polecenie, więc asystent nie może wyczyścić danych ani zmienić konfiguracji. Tryb tylko do odczytu usuwa każde narzędzie zapisu, a przestrzeń nazw ogranicza agenta do jednego prefiksu kluczy. Zainstaluj go przez pip install hotkv-mcp lub uruchom przez uvx.

Czym jest Model Context Protocol

Model Context Protocol, czyli MCP, to otwarty standard łączenia aplikacji AI z systemami zewnętrznymi, takimi jak źródła danych, narzędzia i przepływy pracy. Wprowadzenie projektu porównuje go do portu USB-C dla aplikacji AI. W terminologii MCP aplikacja jest klientem, a każdy system, z którym się łączy, jest udostępniany przez serwer.

W przypadku pamięci oznacza to, że asystent wywołuje nazwane narzędzie, na przykład zapisujące notatkę. Serwer decyduje, co to narzędzie może robić. Model nigdy nie dostaje własnego połączenia z bazą danych.

Co udostępnia serwer MCP HotKV

Serwer opakowuje pamięć agentów HotKV, rejestr promptów i wyszukiwanie dokumentów w 28 narzędzi. Każde narzędzie deklaruje w adnotacjach MCP, czy tylko czyta, zapisuje czy usuwa. Klient może wtedy prosić o zatwierdzenie przed tymi destrukcyjnymi.

Narzędzia pamięci odpowiadają magazynom opisanym w artykule pamięć agentów AI, czyli historii konwersacji, notatkom roboczym i dziennikowi zdarzeń. Przywoływanie semantyczne przez embedding nie jest udostępnione. rag_search szereguje według trafności słów kluczowych, więc żadnego nie potrzebuje.

Narzędzia do kluczy, hashy i list działają z każdym serwerem HotKV. Narzędzia pamięci, promptów i wyszukiwania dokumentów korzystają z silników AI HotKV, które wymagają licencji je obejmującej. Bez niej te narzędzia zwracają komunikat, że serwer nie ma licencji na tę funkcję. Narzędzia kluczy nadal działają. Instancje HotKV Cloud Performance i Scale zawierają silniki AI, jak opisuje strona AI.

Instalacja i połączenie

Serwer wymaga Pythona 3.10 lub nowszego. Został napisany pod serwer HotKV 0.3.0 i oficjalny pakiet hotkv-client, a wersja 1.0.0 jest na PyPI. Zainstaluj go przez pip albo uruchom bez instalacji za pomocą uv.

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

Claude Code

Dodaj go jednym poleceniem. Znak -- oddziela własne opcje Claude Code od polecenia uruchamiającego serwer, jak opisuje dokumentacja MCP w Claude Code.

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

Cursor i Claude Desktop

Klienci czytający plik mcpServers przyjmują ten sam serwer jako wpis JSON. Trzymaj hasło w zmiennej środowiskowej HOTKV_URL lub w magazynie sekretów klienta. Wiersz poleceń jest widoczny dla innych użytkowników maszyny. Użyj hotkvs:// dla połączenia TLS.

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

Sprawdź, czy działa

Uruchom claude mcp list, aby potwierdzić, że serwer jest zarejestrowany. Potem poproś asystenta o wywołanie narzędzia server_info. Zwraca wersję HotKV i zużycie pamięci, a także liczbę kluczy, gdy nie ustawiono przestrzeni nazw. Raportuje również, czy serwer jest tylko do odczytu i jaką przestrzenią nazw jest ograniczony. To potwierdza, że Twoje zabezpieczenia zadziałały.

Trzymaj agenta w bezpiecznych granicach

Model, który może wywoływać narzędzia, może też zostać namówiony do ich nadużycia, więc granice mają większe znaczenie niż funkcje.

Żadnych dowolnych poleceń

Nie ma narzędzia uruchamiającego surowe polecenie. Asystent nie może wyczyścić bazy ani zmienić konfiguracji serwera, ponieważ żadne z 28 narzędzi tego nie robi. Może odczytać każdy klucz, do którego dotarcie umożliwiają narzędzia, dlatego przestrzeń nazw opisana niżej ma znaczenie.

Tryb tylko do odczytu

--read-only usuwa każde narzędzie zapisujące, w tym set, delete, hash_set, list_push, narzędzia pamięci, które dodają lub czyszczą, prompt_save, rag_create i rag_ingest. Agent nawet ich nie widzi. Użyj go dla asystentów, którzy mają korzystać z pamięci, ale nigdy jej nie zmieniać.

Przestrzenie nazw i limity rozmiaru

--namespace PREFIX zapisuje wszystko pod tym prefiksem. Agent nigdy nie widzi prefiksu i nie może dotrzeć do innych nazw. Daj każdemu agentowi prefiks, który nie jest początkiem prefiksu innego. Użyj agent-a i agent-b, a nie agent i agent:b, bo krótszy może dotrzeć do nazw dłuższego.

Wyniki też są ograniczane. --max-value-bytes obcina długie wartości i oznacza je jako obcięte, z domyślną wartością 65 536 bajtów. --max-items ogranicza, ile kluczy, elementów listy lub trafień zwraca wywołanie, domyślnie 200. Pojedyncza ogromna wartość nie może więc zalać kontekstu modelu. Odczyt całego hasha nie jest ograniczony liczbą elementów, więc nie trzymaj dużych hashy w przestrzeni nazw agenta.

Transport HTTP nie ma logowania

Domyślny transport stdio jest uruchamiany przez klienta jako podproces. Do wspólnego użytku możesz uruchomić hotkv-mcp --transport streamable-http, który nasłuchuje na 127.0.0.1:8000 pod /mcp. Nie uwierzytelnia wywołujących. Trzymaj go na localhoście lub umieść za reverse proxy, które to robi, i nadaj mu własną przestrzeń nazw.

Wybór konfiguracji dla zespołu

Właściwe flagi zależą od tego, do czego służy każdy agent. Każda poniższa opcja to flaga wiersza poleceń. --read-only i --namespace mają także zmienne środowiskowe, HOTKV_MCP_READ_ONLY i HOTKV_MCP_NAMESPACE.

Zacznij od najbardziej restrykcyjnego wiersza, który załatwia sprawę. Łatwo później poszerzyć dostęp, a trudno cofnąć to, co agent już zapisał.

Pierwsza sesja krok po kroku

Krótka próba pokazuje, co robią zabezpieczenia, zanim zaufasz serwerowi prawdziwymi notatkami. Użyj jednorazowej przestrzeni nazw i lokalnego serwera HotKV z licencją na silniki AI, ponieważ narzędzia pamięci bez niej nie działają.

1. Połącz z przestrzenią nazw. Uruchom claude mcp add hotkv -- uvx hotkv-mcp --url hotkv://localhost:6379 --namespace trial.
2. Sprawdź limity. Poproś asystenta o wywołanie server_info i podanie przestrzeni nazw oraz tego, czy serwer jest tylko do odczytu. Powinien powiedzieć trial i że nie jest tylko do odczytu.
3. Zapisz notatkę. Poproś o zapamiętanie, że witryna stagingowa jest pod danym adresem, w notatce nazwanej od witryny. Asystent wywołuje memory_set_note, a sesja jest tworzona przy pierwszym użyciu.
4. Odczytaj ją w nowym czacie. Zacznij nową rozmowę i zapytaj, jakie notatki istnieją dla tej sesji. Wywołuje memory_list_notes i memory_get_note, a notatka nadal tam jest.
5. Zapisz decyzję. Poproś o zapisanie decyzji w dzienniku zdarzeń. Wywołuje memory_log_event, a memory_query_events przywraca ją później.
6. Odbierz dostęp do zapisu. Usuń stary wpis, połącz ponownie z --read-only i powtórz krok 4. Odczyt nadal działa, a narzędzia zapisujące nie są już oferowane.

Jeśli krok 6 zachowuje się jak opisano, widziałeś dwa najważniejsze mechanizmy kontroli: przestrzeń nazw i tryb tylko do odczytu.

Traktuj wszystko, co asystent zapisuje, jako niezaufany tekst przy odczycie, jak wyjaśnia artykuł o pamięci w sekcji traktuj zapisany tekst jako niezaufany. Notatki zapisane ze stron internetowych mogą zawierać instrukcje.

Rozwiązywanie problemów

• „This HotKV server is not licensed for that feature.” Narzędzia pamięci, promptów i wyszukiwania dokumentów wymagają licencji HotKV obejmującej silniki AI. Narzędzia do kluczy, hashy i list działają bez niej.
• Połączenie się nie udaje. Sprawdź schemat adresu URL. Działają hotkv://, hotkvs:// (TLS), redis:// i rediss://, a hasło wpisuje się w adres jako hotkv://:password@host:6379.
• Wartość wraca obcięta. Wynik jest oznaczany jako obcięty, gdy przekracza --max-value-bytes. Podnieś limit lub zapisuj mniejsze wartości.
• Brakuje narzędzia zapisu. Poszukaj --read-only w argumentach serwera lub HOTKV_MCP_READ_ONLY w jego środowisku.
• Asystent nie znajduje nazwy, którą zapisał wcześniej. Sprawdź, czy użył tej samej nazwy sesji lub agenta i czy serwer działa z tą samą przestrzenią nazw co wcześniej.
• Nie znaleziono uvx. Zainstaluj uv albo zainstaluj pakiet przez pip i uruchom hotkv-mcp bezpośrednio.

Najczęściej zadawane pytania