Integrations
MCP 接入

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_xxxDashboard 创建的 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. 正文使用 1) 2) 3) 编号；嵌套要点用 a. b. c.。
  3. 不要使用 1. 有序列表、- 列表项、**加粗** 或 > 引用 等 markdown 装饰。
  4. 段与段之间留空行；同一段内可以是多句话或带嵌套编号的小节。
  5. 必须保留专有名词、版本号、路径、命令、API 名、数字、URL，不要包成代码块。
  6. 整体长度建议小于 2000 字符。结尾可用「适用范围：」或「备注：」做总结。
  7. 严禁写入密钥、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。

推荐 metadata

字段示例说明
projectmemaster仓库或产品名
areaserver-golang/docs代码或文档区域
scopedocs-navigation主题范围
sourceclaude-code来源编辑器或工具
memory_typedebug / 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
401API Key 是否有效，请求是否使用 X-API-Key: msk_xxx
404Endpoint 是否为 https://api.memaster.cn/mcp 或私有化实例的 /mcp
检索为空写入和检索的 user_id / agent_id / metadata 是否一致
召回内容混乱是否缺少 project、area、source 过滤

下一步

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