memory-mcp

为 AI 智能体提供持久化、可搜索、带版本控制的记忆功能 —— 由 Valkey（兼容 Redis）提供支持，并通过 HTTP 以 MCP 服务器形式暴露。

适用于任何兼容 MCP 的智能体：Claude Code、Cursor、VS Code 等。

功能特性

• 存储带有标签、类型和项目作用域的命名记忆条目

• 支持标签交集搜索、类型/项目过滤以及子字符串搜索

• 点击追踪（被访问次数多的条目会排在前面）

• 完整的版本历史记录及回滚功能

• Prometheus 指标端点

• 可选的 Bearer Token 认证

快速开始

cp .env.example .env
# Optional: set MEMORY_MCP_AUTH_TOKEN in .env (see Auth section)
docker compose up -d

这将从 GHCR 拉取预构建的镜像。现在 MCP 服务器可在 http://127.0.0.1:3106/mcp 访问。

如需本地构建：

docker compose build
docker compose up -d

使用现有的 Redis 或 Valkey

默认情况下，docker compose up -d 会启动一个捆绑的 Valkey 容器。若要连接到现有的 Redis 或 Valkey 实例，请设置 VALKEY_URL 并仅启动 memory-mcp 服务：

# .env
VALKEY_URL=redis://your-host:6379

docker compose up -d memory-mcp

任何兼容 Redis 的服务器（Redis 6+、Valkey、KeyDB、通过 rediss:// 连接的 Upstash 等）均可使用。该服务器仅使用基础数据结构：哈希、列表和集合。

智能体设置

将本仓库中的 AGENTS.md 复制到你的项目根目录。它会告知你的智能体如何使用记忆工具、存储什么内容以及何时存储。

然后向你的智能体客户端注册该 MCP 服务器：

Claude Code

# Without auth
claude mcp add memory --transport http http://127.0.0.1:3106/mcp

# With auth
claude mcp add memory --transport http http://127.0.0.1:3106/mcp \
  --header "Authorization: Bearer your-token"

或者手动添加到 ~/.claude.json：

{
  "mcpServers": {
    "memory": {
      "type": "http",
      "url": "http://127.0.0.1:3106/mcp",
      "headers": { "Authorization": "Bearer your-token" }
    }
  }
}

Cursor

添加到 ~/.cursor/mcp.json（全局）或 .cursor/mcp.json（项目）：

{
  "mcpServers": {
    "memory": {
      "url": "http://127.0.0.1:3106/mcp",
      "headers": { "Authorization": "Bearer your-token" }
    }
  }
}

VS Code (GitHub Copilot, MCP 扩展)

添加到项目中的 .vscode/mcp.json：

{
  "servers": {
    "memory": {
      "type": "http",
      "url": "http://127.0.0.1:3106/mcp",
      "headers": { "Authorization": "Bearer your-token" }
    }
  }
}

如果你不使用认证，请在任何配置中省略 headers / Authorization 行。

配置

将 .env.example 复制为 .env 并根据需要进行编辑。

认证

默认情况下，服务器在未认证状态下运行。当绑定到回环地址 (127.0.0.1) 且仅从本地机器访问时，这是安全的。

若要启用认证：

# Generate a token
openssl rand -hex 32

# Add to .env
MEMORY_MCP_AUTH_TOKEN=your-generated-token

docker compose up -d

此后所有对 POST /mcp 的请求必须包含：

Authorization: Bearer <token>

GET /health 和 GET /metrics 始终无需认证。

可用工具

记忆类型

pattern（模式）, decision（决策）, reference（参考）, feedback（反馈）, incident（事件）, project（项目）, entity（实体）, state（状态）

端点

数据模型

每个条目都作为 Redis 哈希存储在 mem:<id> 中：

版本历史记录存储在 memver:<id> 的 Redis 列表中（最新优先，上限为 MAX_VERSIONS_PER_ENTRY）。

标签、类型和项目索引为 Redis 集合 (tag:<name>, type:<name>, project:<name>)。

许可证

MIT