Model Context Protocol

MCP 可以把 Memaster 的记忆写入和检索能力暴露为工具，让支持 MCP 的 AI 客户端在对话中主动保存和召回长期记忆。如果你的编辑器更适合通过规则、技能或工作流编排记忆流程，请查看 Skills 接入。

对 AI 编辑器来说，MCP 是最通用的接入方式：Claude Code、Cursor 以及其它支持 MCP 的客户端都可以通过同一组工具访问 Memaster。 Memaster 负责云端存储、向量检索、API Key 鉴权和 Dashboard 可视化。

适用场景

AI 编辑器需要记住项目规则和用户偏好。
桌面 Agent 需要跨会话保留上下文。
内部工具需要统一通过 Memaster 管理长期记忆。
多个编辑器需要共享同一套长期项目记忆。

接入架构

AI Editor ── Remote HTTP MCP ──> https://api.memaster.cn/mcp ──> Memaster Memory Store

Memaster 已内置托管式远程 HTTP MCP endpoint：

Endpoint：POST https://api.memaster.cn/mcp
Transport：Stateless HTTP / JSON-RPC
鉴权：X-API-Key: msk_xxx，也兼容 Authorization: Bearer <access_token>
Discovery：GET https://api.memaster.cn/mcp

这意味着支持远程 HTTP MCP 的客户端不需要在本地安装或启动额外 MCP Server，只需要配置 URL 和 API Key。

⚠️

MCP 工具可以读取编辑器传入的上下文。请只写入稳定、可复用且不包含密钥的事实，不要保存 Token、私钥、密码或 .env 里的真实值。

配置流程

创建 API Key

打开 Dashboard → API Keys，创建 msk_xxx 形式的密钥。

配置远程 MCP Endpoint

在支持远程 HTTP MCP 的客户端中添加 Memaster：

URL：https://api.memaster.cn/mcp
Header：X-API-Key: msk_xxx

私有化部署时，把域名替换为你的实例地址，例如 https://your-api.example.com/mcp。

验证工具列表

客户端连接成功后，应能看到 memaster_add、memaster_search、memaster_profile、memaster_list、memaster_update 和 memaster_delete。

连接参数

参数	必填	示例	说明
Endpoint URL	是	`https://api.memaster.cn/mcp`	远程 HTTP MCP 地址
`X-API-Key`	是	`msk_xxx`	Dashboard 创建的 API Key
`user_id` 工具参数	建议	`alice`	终端用户或开发者标识；不传时默认当前 API Key 所属账号
`agent_id` 工具参数	建议	`cursor`	编辑器或 Agent 标识
`metadata.source`	建议	`mcp`	记忆来源，用于 metadata 过滤；不传时默认 `mcp`
`metadata.project`	建议	`my-project`	仓库或产品标识

远程 MCP 的 owner_user_id 始终来自 API Key 所属账号；工具参数 user_id 用于区分终端用户或开发者。现有 REST POST /memories 会把 user_id 固定为认证账号，因此如果同时使用 REST 和 MCP，请优先通过 metadata.project、metadata.source、agent_id 保持过滤一致。

工具契约

工具	用途
`memaster_add`	写入一条长期记忆
`memaster_search`	按语义检索相关记忆
`memaster_profile`	获取用户画像或偏好摘要
`memaster_list`	按用户、项目、来源或标签列出记忆
`memaster_update`	更新指定记忆
`memaster_delete`	删除错误或敏感记忆

写入内容格式

memaster_add / memaster_update 的 memory / text 字段必须是一段整理过的、纯文本编号列表，禁止直接写入对话原文、堆栈或未整理段落。

格式约定：

首行是主题句，名词短语或一句完整描述，可在末尾用括号补充范围或前提，以「：」结尾。
正文使用 1) 2) 3) 编号；嵌套要点用 a. b. c.。
不要使用 1. 有序列表、- 列表项、**加粗** 或 > 引用 等 markdown 装饰。
段与段之间留空行；同一段内可以是多句话或带嵌套编号的小节。
必须保留专有名词、版本号、路径、命令、API 名、数字、URL，不要包成代码块。
整体长度建议小于 2000 字符。结尾可用「适用范围：」或「备注：」做总结。
严禁写入密钥、token、密码、cookie、证书、原始 .env 值或敏感 PII。

好示例：

Memaster dashboard 包管理器约定：
1) server-golang/dashboard 默认使用 pnpm，禁止 npm 或 yarn。
2) 安装依赖必须执行 pnpm install --frozen-lockfile。

备注：CI 在 .github/workflows/dashboard.yml 校验 lockfile 一致性。

坏示例（不要这样写）：

用户说项目用pnpm  我跑了pnpm install 报错 ERR_INVALID_PACKAGE 然后我换成npm i ...

`memaster_add`

{
  "memory": "Memaster dashboard 包管理器约定：\n1) server-golang/dashboard 默认使用 pnpm，禁止 npm 或 yarn。\n2) 安装依赖必须执行 pnpm install --frozen-lockfile。",
  "user_id": "alice",
  "agent_id": "cursor",
  "metadata": {
    "project": "memaster",
    "area": "server-golang/dashboard",
    "source": "cursor",
    "memory_type": "project_info",
    "tags": ["项目", "规范", "包管理"]
  }
}

远程 MCP endpoint 会在服务端转换为内部记忆写入：

POST /mcp
X-API-Key: msk_xxx
Content-Type: application/json

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "memaster_add",
    "arguments": {
      "memory": "Memaster dashboard 包管理器约定：\n1) server-golang/dashboard 默认使用 pnpm，禁止 npm 或 yarn。\n2) 安装依赖必须执行 pnpm install --frozen-lockfile。",
      "user_id": "alice",
      "agent_id": "cursor",
      "metadata": {
        "project": "memaster",
        "area": "server-golang/dashboard",
        "source": "cursor",
        "memory_type": "project_info",
        "tags": ["项目", "规范", "包管理"]
      }
    }
  }
}

`memaster_search`

{
  "query": "这个项目默认使用什么包管理器？",
  "user_id": "alice",
  "agent_id": "cursor",
  "top_k": 5,
  "filters": {
    "project": "memaster",
    "source": "cursor"
  }
}

远程 MCP endpoint 会在服务端转换为内部语义检索：

POST /mcp
X-API-Key: msk_xxx
Content-Type: application/json

{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "tools/call",
  "params": {
    "name": "memaster_search",
    "arguments": {
      "query": "这个项目默认使用什么包管理器？",
      "user_id": "alice",
      "agent_id": "cursor",
      "top_k": 5,
      "filters": {
        "project": "memaster",
        "source": "cursor"
      }
    }
  }
}

远程 HTTP MCP 配置模板

不同编辑器的字段名可能不同；如果客户端支持远程 HTTP MCP，配置核心就是 URL 和 Header：

mcp.json

{
  "mcpServers": {
    "memaster": {
      "type": "http",
      "url": "https://api.memaster.cn/mcp",
      "headers": {
        "X-API-Key": "msk_xxx"
      }
    }
  }
}

如果某个编辑器当前只支持本地 stdio MCP，则需要一个本地 bridge 转发到 https://api.memaster.cn/mcp。但对支持远程 HTTP MCP 的客户端，Memaster 不需要本地部署 MCP Server。

字段	示例	说明
`project`	`memaster`	仓库或产品名
`area`	`server-golang/docs`	代码或文档区域
`scope`	`docs-navigation`	主题范围
`source`	`claude-code`	来源编辑器或工具
`memory_type`	`debug` / `implementation` / `user_preference`	记忆类型
`tags`	`["文档", "编辑器", "MCP"]`	标签

使用建议

将稳定偏好、项目规范和长期事实写入 Memaster。
不要写入密码、Token、私钥或其它敏感信息。
使用 metadata 标记项目、来源和工具名，方便后续过滤。
复杂任务开始前先检索，完成后只保存已验证结论。
如果旧结论失效，优先更新或删除对应记忆，避免错误召回。

验证接入

在编辑器中执行两步：

调用 memaster_add 记住：这个项目的文档站位于 server-golang/docs，并使用 Nextra。

然后开启新会话或清空上下文后再问：

先调用 memaster_search，再回答：这个项目的文档站在哪里，使用什么框架？

如果能召回 server-golang/docs 和 Nextra，说明 MCP → Memaster → 召回链路正常。

故障排查

现象	检查项
工具不可见	编辑器是否支持远程 HTTP MCP，URL 是否配置为 `/mcp`，Header 是否包含 `X-API-Key`
401	API Key 是否有效，请求是否使用 `X-API-Key: msk_xxx`
404	Endpoint 是否为 `https://api.memaster.cn/mcp` 或私有化实例的 `/mcp`
检索为空	写入和检索的 `user_id` / `agent_id` / metadata 是否一致
召回内容混乱	是否缺少 `project`、`area`、`source` 过滤

下一步

Skills 接入 Claude Code 接入 Cursor 接入 REST API

Skills 接入 Claude Code