Сервер MCP для пам'яті агента: підключіть Claude Code до HotKV

Сервер MCP це найпростіший спосіб дати асистентові ШІ пам'ять, що триває довше за один чат. Claude Code, Cursor та подібні клієнти втрачають контекст чату, коли він завершується. Надавати їм прямий доступ до бази даних, щоб це виправити, ризиковано. hotkv-mcp це наш сервер MCP з відкритим кодом для HotKV. Він дає асистентові фіксований набір інструментів для нотаток, історії розмови, журналу подій, шаблонів промптів і пошуку документів. Нічого іншого він не пропонує.

Коротко. hotkv-mcp є сервером MCP за ліцензією Apache-2.0, що підключає Claude Code, Cursor, VS Code або вашого власного агента до сервера HotKV через 28 фіксованих інструментів. Немає інструмента, що виконує довільну команду, тож асистент не може очистити дані чи змінити конфігурацію. Режим лише для читання прибирає кожен інструмент запису, а простір імен обмежує агента одним префіксом ключів. Встановіть його через pip install hotkv-mcp або запустіть через uvx.

Що таке Model Context Protocol

Model Context Protocol, або MCP, це відкритий стандарт для підключення застосунків ШІ до зовнішніх систем, як-от джерела даних, інструменти та робочі процеси. Вступ проєкту порівнює його з портом USB-C для застосунків ШІ. У термінах MCP застосунок є клієнтом, а кожну систему, до якої він підключається, відкриває сервер.

Для пам'яті це означає, що асистент викликає іменований інструмент, наприклад той, що зберігає нотатку. Сервер вирішує, що цьому інструменту дозволено. Модель ніколи не отримує власного з'єднання з базою даних.

Що відкриває сервер HotKV MCP

Сервер обгортає пам'ять агентів HotKV, реєстр промптів і пошук документів у 28 інструментів. Кожен інструмент оголошує у своїх анотаціях MCP, чи він лише читає, пише або видаляє. Тоді клієнт може запитувати підтвердження перед руйнівними.

Інструменти пам'яті відповідають сховищам, описаним у статті про пам'ять агента ШІ, а саме історії розмови, робочим нотаткам і журналу подій. Семантичне пригадування за ембедингом не відкрито. rag_search ранжує за ключовою релевантністю, тож не потребує його.

Інструменти ключів, хешів і списків працюють з будь-яким сервером HotKV. Інструменти пам'яті, промптів і пошуку документів використовують рушії ШІ HotKV, для яких потрібна ліцензія, що їх включає. Без неї ці інструменти повертають повідомлення, що сервер не має ліцензії на цю функцію. Інструменти ключів продовжують працювати. Екземпляри HotKV Cloud Performance і Scale включають рушії ШІ, як описує сторінка ШІ.

Встановлення та підключення

Серверу потрібен Python 3.10 або новіший. Його написано під сервер HotKV 0.3.0 та офіційний пакет hotkv-client, а версія 1.0.0 є на PyPI. Встановіть його через pip або запустіть без встановлення через uv.

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

Claude Code

Додайте його однією командою. Роздільник -- відокремлює власні опції Claude Code від команди, що запускає сервер, як описує документація MCP для Claude Code.

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

Cursor і Claude Desktop

Клієнти, що читають файл mcpServers, приймають той самий сервер як запис JSON. Тримайте пароль у змінній середовища HOTKV_URL або в сховищі секретів клієнта. Командний рядок видно іншим користувачам машини. Використовуйте hotkvs:// для з'єднання TLS.

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

Перевірте, що це працює

Виконайте claude mcp list, щоб підтвердити, що сервер зареєстровано. Потім попросіть асистента викликати інструмент server_info. Він повертає версію HotKV і використання пам'яті, а також кількість ключів, якщо простір імен не задано. Він також повідомляє, чи сервер працює лише для читання і яким простором імен обмежений. Це підтверджує, що ваші запобіжники подіяли.

Тримайте агента в безпечних межах

Модель, що може викликати інструменти, може бути також умовлена їх зловживати, тож межі важливіші за функції.

Жодних довільних команд

Немає інструмента, що виконує сиру команду. Асистент не може очистити базу даних чи змінити конфігурацію сервера, бо жоден із 28 інструментів цього не робить. Він може читати будь-який ключ, якого сягають інструменти, тому простір імен нижче має значення.

Режим лише для читання

--read-only прибирає кожен інструмент, що пише, зокрема set, delete, hash_set, list_push, інструменти пам'яті, що додають чи очищають, prompt_save, rag_create і rag_ingest. Агент їх навіть не бачить. Використовуйте його для асистентів, які мають звертатися до пам'яті, але ніколи її не змінювати.

Простори імен і обмеження розміру

--namespace PREFIX зберігає все під цим префіксом. Агент ніколи не бачить префікс і не може дістатися до інших імен. Дайте кожному агентові префікс, що не є початком іншого. Використовуйте agent-a і agent-b, а не agent і agent:b, інакше коротший може дістатися до імен довшого.

Результати теж обмежені. --max-value-bytes обрізає довгі значення й позначає їх як обрізані, типово 65 536 байтів. --max-items обмежує, скільки ключів, елементів списку чи збігів повертає виклик, типово 200. Тож одне величезне значення не може заповнити контекст моделі. Читання цілого хеша не обмежене за кількістю елементів, тож тримайте великі хеші поза простором імен агента.

У транспорту HTTP немає входу

Типовий транспорт stdio запускається клієнтом як підпроцес. Для спільного використання ви можете запустити hotkv-mcp --transport streamable-http, що слухає на 127.0.0.1:8000 за адресою /mcp. Він не автентифікує тих, хто викликає. Тримайте його на localhost або поставте за зворотний проксі, який це робить, і дайте йому власний простір імен.

Вибір конфігурації для команди

Правильні прапорці залежать від призначення кожного агента. Кожна опція нижче є прапорцем командного рядка. --read-only і --namespace також мають змінні середовища, HOTKV_MCP_READ_ONLY і HOTKV_MCP_NAMESPACE.

Починайте з найбільш обмеженого рядка, який виконує завдання. Доступ легко розширити пізніше, а повернути те, що агент уже записав, важко.

Перша сесія, крок за кроком

Коротке випробування показує, що роблять запобіжники, перш ніж довірити серверу справжні нотатки. Використайте тимчасовий простір імен і локальний сервер HotKV, ліцензований на рушії ШІ, бо без цієї ліцензії інструменти пам'яті не працюють.

1. Підключіться з простором імен. Виконайте claude mcp add hotkv -- uvx hotkv-mcp --url hotkv://localhost:6379 --namespace trial.
2. Перевірте межі. Попросіть асистента викликати server_info і повідомити простір імен та чи сервер працює лише для читання. Він має сказати trial і що не лише для читання.
3. Збережіть нотатку. Попросіть його запам'ятати, що staging-сайт живе за певною адресою, під нотаткою з назвою сайту. Асистент викликає memory_set_note, а сесію створюють при першому використанні.
4. Прочитайте її в новому чаті. Почніть свіжу розмову й запитайте, які нотатки існують для тієї сесії. Він викликає memory_list_notes і memory_get_note, і нотатка досі там.
5. Запишіть рішення. Попросіть його записати рішення в журнал подій. Він викликає memory_log_event, а memory_query_events повертає його пізніше.
6. Заберіть право запису. Видаліть старий запис, перепідключіться з --read-only і повторіть крок 4. Читання все ще працює, а інструменти запису більше не пропонуються.

Якщо крок 6 поводиться як описано, ви побачили два засоби контролю, що мають найбільше значення, простір імен і режим лише для читання.

Ставтеся до всього, що зберігає асистент, як до недовіреного тексту під час читання назад, як пояснює стаття про пам'ять у розділі про ставлення до збереженого тексту як до недовіреного. Нотатки, записані з вебсторінок, можуть нести інструкції.

Усунення несправностей

• «This HotKV server is not licensed for that feature.» Інструменти пам'яті, промптів і пошуку документів потребують ліцензії HotKV, що включає рушії ШІ. Інструменти ключів, хешів і списків продовжують працювати без неї.
• З'єднання не вдається. Перевірте схему URL. Працюють hotkv://, hotkvs:// (TLS), redis:// і rediss://, а пароль іде в URL як hotkv://:password@host:6379.
• Значення повернулося обрізаним. Результат позначається як обрізаний, коли перевищує --max-value-bytes. Підвищте ліміт або зберігайте менші значення.
• Бракує інструмента запису. Пошукайте --read-only в аргументах сервера або HOTKV_MCP_READ_ONLY у його середовищі.
• Асистент не знаходить ім'я, збережене раніше. Перевірте, що він використав ту саму назву сесії чи агента і що сервер працює з тим самим простором імен, що й раніше.
• uvx не знайдено. Встановіть uv або встановіть пакет через pip і запустіть hotkv-mcp безпосередньо.

Поширені запитання