Memory MCP Server (Go)

Memory MCP Server (Go)

一个提供知识图谱管理能力的模型上下文协议服务。此服务可让大模型在持久化知识图谱中创建、读取、更新和删除实体及关系，帮助 AI 助手在不同对话之间保持记忆。这是官方 TypeScript Memory MCP Server 的 Go 实现。

功能

• 高性能存储：采用 SQLite 后端和 WAL 模式，并分离读写连接以支持并发访问
• 知识图谱管理：持久化存储实体、关系和观察记录
• 高级搜索：使用 FTS5 全文搜索、BM25 排名、同义词扩展和时间衰减评分
• 图遍历：搜索结果包含 1 跳相关实体，提供更丰富的上下文
• 实体管理：合并重复实体、更新类型、修改观察记录、检测冲突
• 观察记录元数据：跟踪每条观察记录的来源、置信度和标签
• MCP 资源和提示词：AI 客户端可被动加载图谱摘要，并使用引导式记忆工作流
• 灵活的传输方式：支持 stdio、SSE 和 Streamable HTTP，并可选择使用 Bearer 或 OAuth 2.1 身份验证
• 无缝迁移：从 JSONL 自动升级到 SQLite，无需干预
• 跨平台：纯 Go SQLite（无需 CGO），可在 Linux、macOS 和 Windows 上运行

可用工具

核心 CRUD

工具	描述
create_entities	使用名称、类型和观察记录创建新实体
create_relations	创建实体之间的关系（主动语态）
add_observations	向现有实体添加观察记录
delete_entities	删除实体及其关联关系
delete_relations	删除指定关系
delete_observations	从实体中删除指定观察记录

查询

工具	描述
search_nodes	使用 FTS5、同义词扩展和图遍历按关键词搜索实体。返回包含摘要片段和相关实体的轻量级结果
open_nodes	按精确名称获取指定实体的完整详情
read_graph	获取图谱概览（summary 模式）或完整导出内容（full 模式）

实体管理

工具	描述
merge_entities	合并两个实体：将源实体的观察记录和关系迁移到目标实体，然后删除源实体
update_entities	更改实体类型
update_observations	替换观察记录的内容
detect_conflicts	查找实体观察记录中的潜在重复项和矛盾

MCP 资源

URI	描述
memory://graph/summary	图谱统计信息和实体类型分布
memory://graph/recent	最近访问的实体
memory://graph/types	所有实体和关系类型枚举
memory://entities/{name}	指定实体的完整详情

MCP 提示词

提示词	描述
memory-recall	按主题回忆相关记忆
memory-save	分析对话文本并建议要保存的内容
memory-review	生成实体记忆的全面回顾

安装

Homebrew（macOS/Linux）

brew install okooo5km/tap/mms

快速安装脚本（macOS/Linux）

curl -fsSL https://raw.githubusercontent.com/okooo5km/memory-mcp-server-go/main/scripts/install.sh | bash

选项：使用 -v v0.2.3 指定版本，使用 -d /usr/local/bin 指定自定义目录。

预编译二进制文件

从 GitHub Releases 下载。提供适用于 macOS（arm64/amd64）、Linux（arm64/amd64）和 Windows（arm64/amd64）的版本。

# Example: macOS Apple Silicon
curl -L https://github.com/okooo5km/memory-mcp-server-go/releases/latest/download/mms_VERSION_darwin_arm64.tar.gz | tar xz
chmod +x mms && mv mms ~/.local/bin/

从源代码构建

git clone https://github.com/okooo5km/memory-mcp-server-go.git
cd memory-mcp-server-go
make build        # binary in .build/

确保 ~/.local/bin（或你选择的目录）位于 PATH 中。

命令行参数

mms [options]
  -t, --transport string   Transport type: stdio, sse, or http (default "stdio")
  -m, --memory string      Memory file path (auto-detected if not specified)
  -p, --port int           Port for SSE/HTTP transport (default 8080)
  --host string            Host/IP to bind for SSE/HTTP transports (env: MMS_HOST, default all interfaces)
  -v, --version            Show version

  Storage:
  --storage string         Force storage type: sqlite or jsonl (auto-detected)
  --auto-migrate           Auto-migrate JSONL to SQLite (default true)

  Migration:
  --migrate string         Source JSONL file for manual migration
  --migrate-to string      Destination SQLite file
  --dry-run                Dry run migration
  --force                  Overwrite destination

  Streamable HTTP:
  --http-endpoint string   HTTP endpoint path (default "/mcp")
  --http-heartbeat string  Heartbeat interval (default "30s")
  --http-stateless         Stateless HTTP mode

  Auth:
  --auth-bearer string     Require Bearer token for SSE/HTTP

  OAuth 2.1 (mutually exclusive with --auth-bearer):
  --oauth-user string      OAuth login username (env: OAUTH_USER)
  --oauth-pass string      OAuth login password (env: OAUTH_PASS)
  --oauth-issuer string    OAuth issuer URL (auto-detect if empty, env: OAUTH_ISSUER)
  --oauth-store string     SQLite path for durable OAuth clients and tokens (env: OAUTH_STORE_PATH)
  --oauth-refresh-replay-grace string
                           Duration to accept replay of a rotated refresh token (env: OAUTH_REFRESH_REPLAY_GRACE, default 75m)

  CORS:
  --cors-origin string     Allowed CORS origins: '*' for all, or comma-separated list (default "*")

示例：

mms                                          # stdio, auto-detect storage
mms --memory /path/to/memory.json            # custom path, auto-migrates to SQLite
mms --transport sse --port 9000              # SSE transport
mms --transport http --auth-bearer mytoken   # Streamable HTTP with Bearer auth
mms --transport http --host 127.0.0.1 --oauth-user admin --oauth-pass secret --oauth-store /var/lib/mms/oauth.db  # OAuth 2.1 auth
mms --transport http --cors-origin "https://app.example.com,https://admin.example.com"  # CORS whitelist

配置

Claude Desktop / Claude.app

"mcpServers": {
  "memory": {
    "command": "mms",
    "env": {
      "MEMORY_FILE_PATH": "/path/to/memory.json"
    }
  }
}

Claude Desktop 连接器（OAuth）

使用 OAuth 2.1 身份验证进行远程部署，与 Claude Desktop 的自定义连接器兼容：

# Start server with OAuth
mms --transport http --host 127.0.0.1 --oauth-user admin --oauth-pass secret --oauth-store /var/lib/mms/oauth.db --port 8080

# Or with environment variables and explicit issuer
OAUTH_USER=admin OAUTH_PASS=secret OAUTH_STORE_PATH=/var/lib/mms/oauth.db \
  OAUTH_REFRESH_REPLAY_GRACE=24h \
  mms --transport http --oauth-issuer https://mcp.example.com

然后在 Claude Desktop 中：设置 → 连接器 → 添加自定义连接器 → 输入服务 URL（例如，https://mcp.example.com/mcp）。Claude 会自动发现 OAuth 端点并提示你登录。

Cursor

添加到 Cursor 设置 > mcp.json：

{
  "mcpServers": {
    "memory": {
      "command": "mms",
      "env": {
        "MEMORY_FILE_PATH": "/path/to/memory.json"
      }
    }
  }
}

系统提示词示例

You have access to a Knowledge Graph memory system that persists across conversations.

Saving memories:
- create_entities: Add new people, places, concepts (check search_nodes first to avoid duplicates)
- create_relations: Record how entities relate to each other
- add_observations: Add facts to existing entities

Retrieving memories:
- search_nodes: Find relevant entities by keyword (supports synonyms like JS→JavaScript)
- open_nodes: Get full details of specific entities
- read_graph: Get an overview of all stored knowledge (use "summary" mode first)

Managing memories:
- merge_entities: Combine duplicate entities
- detect_conflicts: Find contradictory observations
- update_entities / update_observations: Fix incorrect data

Always check your memory before answering questions that might require past context.

Streamable HTTP 用法

Streamable HTTP 端点接受 JSON-RPC 请求、通知和响应。根据 MCP 传输规范，对于服务器 ping 消息的回复等客户端响应，会以 202 Accepted 确认，且不包含消息正文。

# 1. Initialize session
curl -i -X POST http://localhost:8080/mcp \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer mytoken' \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-03-26","capabilities":{}}}'

# 2. Listen for server messages
curl -N http://localhost:8080/mcp \
  -H 'Authorization: Bearer mytoken' \
  -H 'Mcp-Session-Id: <session-id>'

# 3. Call a tool
curl -s http://localhost:8080/mcp \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer mytoken' \
  -H 'Mcp-Session-Id: <session-id>' \
  -d '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"search_nodes","arguments":{"query":"idea"}}}'

# 4. Terminate session
curl -X DELETE http://localhost:8080/mcp \
  -H 'Authorization: Bearer mytoken' \
  -H 'Mcp-Session-Id: <session-id>'

安全与部署

• 部署在 TLS（Nginx/Caddy/Traefik）后方，并将服务绑定到 localhost
• 简单身份验证：对程序化客户端使用 --auth-bearer $(openssl rand -hex 32)
• OAuth 2.1：对基于浏览器的登录（Claude Desktop Connectors）使用 --oauth-user/--oauth-pass。在生产环境中设置 --oauth-store，使已注册客户端和令牌在重启后仍然保留；并以严格的 umask（例如 systemd UMask=0077）运行服务，以保护 SQLite WAL/SHM 文件。支持 PKCE（S256）、动态客户端注册、持久化令牌存储，以及刷新令牌轮换（为并发或多工作进程客户端提供重放宽限期）。对于在多个进程中保留过期刷新令牌的客户端，请使用 --oauth-refresh-replay-grace
• 将 Authorization 标头从反向代理转发到后端；在代理后方时，将 --oauth-issuer 设置为公开 URL
• 以非 root 用户身份运行，只开放必需端口，并为不受信任的客户端启用速率限制

存储系统

存储类型

	SQLite（推荐）	JSONL（旧版）
读取/搜索	快 1.9 倍	基准
内存	效率高 1.9 倍	基准
文件大小	更大	小 3 倍
启动	更慢	快 55 倍
功能	FTS5、ACID、WAL、并发读取	人类可读
适用场景	>100 个实体	<50 个实体

迁移

# Automatic (default): just use your existing JSONL path
mms --memory /path/to/memory.json  # auto-migrates to .db

# Manual migration
mms --migrate /path/to/memory.json --migrate-to /path/to/memory.db

# Dry run
mms --migrate /path/to/memory.json --dry-run

知识图谱结构

• 实体：包含名称、类型和观察列表的节点（每条观察都可包含可选元数据：来源、置信度、标签）
• 关系：实体之间的有向边，关系类型采用主动语态
• 观察：与实体关联的原子事实，支持根据访问模式进行时间衰减排序

用法示例

创建实体

{
  "entities": [
    {
      "name": "John Smith",
      "entityType": "person",
      "observations": ["Software engineer", "Lives in San Francisco", "Enjoys hiking"]
    },
    {
      "name": "Acme Corp",
      "entityType": "company",
      "observations": ["Founded in 2010", "Tech startup"]
    }
  ]
}

创建关系

{
  "relations": [
    { "from": "John Smith", "to": "Acme Corp", "relationType": "works at" }
  ]
}

使用图遍历进行搜索

搜索 “John” 会返回：

• 直接命中：与 “John” 匹配的实体及其观察摘要
• 相关实体：通过关系与 “John” 相连的实体（例如，通过 “works at” 关联到 “Acme Corp”）

合并重复实体

{
  "sourceName": "React.js",
  "targetName": "React"
}

将 “React.js” 的所有观察和关系合并到 “React”，然后删除 “React.js”。

检测冲突

{
  "entityName": "John Smith"
}

返回潜在的重复项（前缀重叠度 >60%）和矛盾项（如 “likes/dislikes” 这样的反义词对）。

开发

make fmt          # Format code
make check        # Static analysis (gofmt + go vet)
go test ./...     # Run tests
make build        # Build binary

# Full verification
make fmt && make check && go test ./... && make build

要求

• Go 1.24+
• github.com/mark3labs/mcp-go v0.19.0+
• modernc.org/sqlite（纯 Go SQLite，无需 CGO）

版本管理

版本通过 VERSION 文件管理。可使用 make build VERSION=1.2.3 或 go build -ldflags "-X main.version=1.2.3" 覆盖。

许可证

MIT 许可证。详情请参阅 LICENSE。