garnet-mcp

Garnet 向量记忆 MCP 服务

一个 MCP（Model Context Protocol） 服务，为大模型 Agent 提供由 Garnet Vector Sets 支持的检索增强生成（RAG）记忆。Agent 将文本存储为嵌入向量，之后可按语义检索最相关的片段，为回答提供依据——记忆可跨会话持久保留，而不只限于单次对话。这是应用层的语义回忆（RAG）：它会用检索到的上下文增强模型提示词，与推理层的 KV 缓存复用（例如 LMCache）有所不同。它可连接到本地或可自托管的开源 Garnet（或任何支持 Vector Sets 的 Redis 兼容端点），并支持自带嵌入模型。

工具

该服务通过 MCP stdio 传输协议提供五个工具（也支持 HTTP）：

工具	说明
store_memory	将事实或文本存入长期记忆。返回记忆 ID。
recall_memory	对已存储的记忆进行语义搜索；返回最匹配的结果及其分数。
forget_memory	根据 ID 删除已存储的记忆。
list_indexes	列出当前存在的向量集记忆索引。
index_info	显示记忆索引键的元数据（度量方式、维度、大小）。

前置条件

• .NET 10 SDK —— 客户端需要它才能通过 dnx 命令启动服务（该命令随 .NET 10 SDK 提供）。该程序包本身面向 net9.0。
• 已启用 Vector Sets 的 Garnet 服务。 Vector Sets 目前是 Garnet 的预览功能，必须通过 --enable-vector-set-preview 显式启用。任何支持 V* 向量命令的 Redis 兼容端点也可以使用。
• 嵌入模型（可选，但建议配置）。 设置 Embeddings__Provider=AzureOpenAI，并将其指向 Azure OpenAI 嵌入部署（可通过 DefaultAzureCredential / az login 使用无密钥身份验证）。未配置时，服务会回退到确定性的 Fake 提供程序，无需外部调用——适用于本地演示和测试，但无法实现有意义的语义回忆。

安装（通过 NuGet）

该服务以 .NET 工具程序包的形式发布，MCP 客户端通过 dnx 运行。将其添加到客户端的 MCP 配置中，例如 VS Code / GitHub Copilot 的 .vscode/mcp.json：

{
  "servers": {
    "garnet-mcp": {
      "type": "stdio",
      "command": "dnx",
      "args": ["[email protected]", "--yes"],
      "env": {
        "Garnet__Host": "127.0.0.1",
        "Garnet__Port": "6379",
        "Embeddings__Provider": "AzureOpenAI",
        "Embeddings__Endpoint": "https://YOUR-RESOURCE.openai.azure.com/",
        "Embeddings__DeploymentName": "text-embedding-3-small",
        "Embeddings__Dimensions": "1536"
      }
    }
  }
}

要运行完全离线的演示，请删除 Embeddings__* 条目（或设置 Embeddings__Provider=Fake）。

推荐的 Agent 指令

该服务会在连接时通过 ServerInstructions 向所有 MCP 客户端发送使用指南，因此大多数 Agent 都能自行恰当地使用这些工具。如果你希望 Agent 主动使用记忆，可在该 Agent 的自定义指令中添加类似以下内容（例如，在你的项目中的 .github/copilot-instructions.md、Claude/Cursor 规则文件等）：

在回答任何关于用户的问题之前——包括他们的偏好、事实、决定或过去的陈述——都必须先调用 recall_memory，即使答案看起来就在当前聊天中（记忆会跨会话保留）。每当用户陈述关于自己的长期事实，或要求你记住某件事时，都要调用 store_memory 保存，然后简要确认已保存的内容。

配置

所有设置均从配置／环境变量读取。使用环境变量形式时，以 __（双下划线）作为区段分隔符。

设置	环境变量	默认值	说明
Garnet 主机	Garnet__Host	127.0.0.1	留空时视为使用默认值。
Garnet 端口	Garnet__Port	6379
键前缀	Garnet__KeyPrefix	mem	内存索引键的前缀。
记录 Redis 命令	Garnet__LogRedisCommands	false	设置为 true 后，会在 Debug 级别记录等效的 redis-cli 命令（用于故障排查）。
日志级别	Logging__LogLevel__Default	Information	默认只输出一行安静的启动日志，以及警告／错误。设置为 Debug 可追踪每次工具调用。使用 stdio 传输时，日志输出到 stderr。
嵌入提供方	Embeddings__Provider	Fake	AzureOpenAI 或 Fake。
Azure OpenAI 终结点	Embeddings__Endpoint	—	提供方为 AzureOpenAI 时必填。
部署名称	Embeddings__DeploymentName	text-embedding-3-small
维度	Embeddings__Dimensions	1536（AOAI）／8（Fake）	必须与嵌入模型匹配。
API 密钥	Embeddings__ApiKey	—	可选；建议使用无密钥的 DefaultAzureCredential。
内存所有者	Memory__User	default	固定内存所有者，确保存储和召回始终一致。
传输方式	Transport	Stdio	Stdio（本地）或 Http（托管）。

嵌入提供方

开箱即用的提供方有两种：

• AzureOpenAI — 提供真实嵌入，是唯一达到生产级质量的选项。可通过 DefaultAzureCredential（或 API 密钥）免密使用。
• Fake — 确定性的离线向量，由哈希作为种子生成。适用于本地运行和测试，但不具备语义意义——请勿用于实际召回。

嵌入生成通过 IEmbeddingProvider 抽象层（EmbedAsync／EmbedBatchAsync，以及 ModelName 和 Dimensions）实现。系统其余部分——GarnetMemoryStore、向量客户端和工具——仅依赖此接口，因此可以引入其他后端（例如 OpenAI、通过 Ollama 提供的本地模型或 Hugging Face），而无需修改这些代码。要添加提供方，请实现 IEmbeddingProvider，并在 Program.cs 的 ConfigureDomain 中，根据对应的 Embeddings__Provider 值注册。

内存所有权（按设计采用单租户）

内存所有者在服务器进程的整个生命周期内由配置固定（Memory__User，默认值为 default）——模型无法在每次调用时自行选择。store_memory 和 recall_memory 均限定于该所有者（召回时会按已存储的 user 属性筛选），因此不同聊天和会话中的存储与召回始终一致。

此设计适用于随附的模型：个人单所有者服务器由你自己的客户端通过 stdio 启动——进程本身就是用户。我们有意避免让模型在每次调用时提供用户，因为这会导致存储与召回不一致（模型的行为并不总是一致），还会允许一个调用方读取或覆盖另一位所有者的记忆。

对于托管式多租户部署（由 Http 传输为多人提供服务），所有者应取自已验证的调用方身份（来自身份验证令牌／标头）——绝不能由模型选择。这是计划未来实现的增强功能，不应通过工具参数传递。

从源代码构建并运行

# Build + test the solution (integration tests self-skip when Garnet/AOAI are unreachable).
dotnet test src/GarnetMcp.slnx

# Run the server directly over stdio.
dotnet run --project src/GarnetMcp.Server

# Optional: interactive console to try store/recall/forget by hand (dev only; not part of the package).
dotnet run --project src/GarnetMcp.Demo

在使用内存工具之前，请启动一个启用了 Vector Sets 的本地 Garnet：

garnet --enable-vector-set-preview true

注意事项

• MCP SDK 预览版。 此项目固定使用 ModelContextProtocol 2.0.0-preview.2。SDK 的 API 范围可能会在不同预览版之间发生变化。
• Garnet Vector Sets 为预览功能。 启动 Garnet 时添加 --enable-vector-set-preview，否则记忆工具会返回清晰的“未启用 Vector Sets”错误。
• 多节点集群上的 list_indexes。 索引枚举会在已连接的节点上使用 SCAN，因此对于可自托管的多节点 Garnet 集群，它只会返回该节点上的键（结果不完整）。单节点／可自托管设置不受影响；无论哪种情况，store_memory／recall_memory／forget_memory 也不受影响（它们针对特定键进行操作）。

许可证

MIT © Tara Zou