Сервер 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 от команды, запускающей сервер, как описано в документации Claude Code по MCP.

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

Cursor и Claude Desktop

Клиенты, читающие файл mcpServers, принимают тот же сервер как запись JSON. Храните пароль в переменной окружения HOTKV_URL или в хранилище секретов клиента. Командная строка видна другим пользователям машины. Для соединения TLS используйте hotkvs://.

{
  "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. Сохраните заметку. Попросите его запомнить, что тестовый сайт находится по заданному адресу, в заметке с именем сайта. Ассистент вызывает 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 напрямую.

Часто задаваемые вопросы