面向智能体记忆的 MCP 服务器：将 Claude Code 连接到 HotKV

要让 AI 助手拥有比一次聊天更持久的记忆，MCP 服务器是最简单的办法。Claude Code、Cursor 和类似的客户端在聊天结束时就会丢掉这次聊天的上下文。为了解决这个问题而把原始的数据库访问权限交给它们，是有风险的。hotkv-mcp 是我们为 HotKV 开源的 MCP 服务器。它给助手提供一组固定的工具，用于笔记、对话历史、事件日志、提示词模板和文档搜索。除此之外，它什么都不提供。

简而言之：hotkv-mcp 是一个 Apache-2.0 许可的 MCP 服务器，通过 28 个固定工具，把 Claude Code、Cursor、VS Code 或您自己的智能体连接到 HotKV 服务器。没有任何工具可以运行任意命令，所以助手无法清空数据或更改配置。只读模式会移除所有写入类工具，命名空间则把智能体限制在一个键前缀之内。用 pip install hotkv-mcp 安装，或者用 uvx 运行。

什么是 Model Context Protocol

Model Context Protocol，简称 MCP，是一项开放标准，用于把 AI 应用连接到数据源、工具和工作流等外部系统。该项目的介绍把它比作 AI 应用的 USB-C 接口。在 MCP 的术语中，应用是客户端，它所连接的每个系统都由一个服务器对外提供。

对记忆来说，这意味着助手调用一个有名字的工具，例如保存笔记的那个工具。该工具能做什么，由服务器决定。模型永远不会得到属于它自己的数据库连接。

HotKV MCP 服务器提供什么

该服务器把 HotKV 的智能体记忆、提示词注册表和文档搜索封装成 28 个工具。每个工具都在其 MCP 注解中声明自己是只读、写入还是删除。这样客户端就可以在执行具有破坏性的工具之前请求批准。

这些记忆工具对应的是 AI 智能体记忆中介绍的存储，即对话历史、工作笔记和事件日志。基于嵌入的语义回忆没有对外提供。rag_search 按关键词相关性排序，所以并不需要它。

键、哈希和列表这几个工具可以对任何 HotKV 服务器使用。记忆、提示词和文档搜索这几个工具使用的是 HotKV 的 AI 引擎，需要包含这些引擎的许可证。没有许可证时，这些工具会返回一条消息，说明该服务器未获得此功能的许可。键相关的工具仍然可以使用。HotKV Cloud 的 Performance 和 Scale 实例包含 AI 引擎，详见 AI 页面。

安装与连接

该服务器需要 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 环境变量或客户端的密钥存储中。命令行对这台机器的其他用户是可见的。需要 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。它不对调用方进行身份验证。请让它保持在本机，或者把它放在会做身份验证的反向代理之后，并为它设置单独的命名空间。

为团队选择配置

合适的参数取决于每个智能体的用途。下面的每个选项都是命令行参数。--read-only 和 --namespace 还有对应的环境变量，即 HOTKV_MCP_READ_ONLY 和 HOTKV_MCP_NAMESPACE。

请从能完成任务的最严格的那一行开始。以后放宽访问权限很容易，而要收回智能体已经写入的内容却很难。

第一次会话，一步一步来

先做一次简短的试用，看看这些安全措施起什么作用，再决定是否把真实的笔记交给这个服务器。请使用一个一次性的命名空间，以及一台获得 AI 引擎许可的本地 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.” 记忆、提示词和文档搜索这几个工具，需要包含 AI 引擎的 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。

常见问题