通过MCP接入PolarDB记忆管理-Claude Code Qoder Hermes Python SDK配置指南-云原生数据库 PolarDB(PolarDB)-阿里云帮助中心

PolarDB记忆管理支持通过MCP（Model Context Protocol）协议接入到主流AI编程助手，让助手自动获得添加、检索与管理长时记忆的能力，无需编写任何代码。本文介绍如何在Claude Code、Qoder、Hermes Agent以及Python MCP SDK中配置PolarDB记忆管理。

前置准备

开始接入前，请按下表准备MCP接入所需的关键参数。

参数	说明
MCP端点	在PolarDB记忆管理的连接地址后拼接`/mcp`路径。连接地址的形式为`<host>:<port>`，因此最终MCP端点为`http://<host>:<port>/mcp`。连接地址的获取方式，请参见步骤二：获取连接地址与访问凭证。
传输协议	Streamable HTTP，基于JSON-RPC 2.0规范。
认证方式	通过请求头`Authorization: Token <your-api-key>`携带API Key（`secret.access.apikey`参数值）。

说明

MCP客户端所在环境需与PolarDB记忆管理网络连通。若客户端运行在本地或非同VPC的环境中，请先申请公网地址，或将本地公网IP加入应用白名单，详情请参见步骤三：配置白名单。
后续示例统一使用环境变量MEM0_API_KEY存放API Key，请提前在操作系统中设置：export MEM0_API_KEY="your-api-key"。

通过Claude Code接入

适用版本：Claude Code 0.2.34及以上。Claude Code支持三种配置方式，可根据您的使用场景选择合适的方式。

接入方式

方式一：命令行快速添加

在终端执行以下命令，一行完成MCP服务注册：

claude mcp add --transport http mem0 http://<host>:<port>/mcp \
  --header "Authorization: Token your-api-key"

验证服务是否添加成功：

claude mcp list

进入Claude Code交互界面后，输入/mcp可查看连接状态。

方式二：项目级配置文件（推荐团队使用）

在项目根目录创建.mcp.json文件并提交到Git，即可实现团队共享：

{
  "mcpServers": {
    "mem0": {
      "type": "http",
      "url": "http://<host>:<port>/mcp",
      "headers": {
        "Authorization": "Token ${MEM0_API_KEY:-apikey}"
      }
    }
  }
}

在终端设置环境变量：

export MEM0_API_KEY="your-api-key"

说明

${MEM0_API_KEY:-apikey}语法表示优先读取环境变量，未设置时回退到默认值apikey，避免密钥硬编码到Git仓库。

方式三：用户级配置（跨项目生效）

若希望在所有项目中都可访问PolarDB记忆管理，可使用用户级作用域：

claude mcp add --transport http mem0 --scope user \
  http://<host>:<port>/mcp \
  --header "Authorization: Token your-api-key"

使用示例

配置完成后直接对话即可，Claude Code会根据对话内容自动调用记忆管理工具：

> 记住我的生产数据库是PolarDB PostgreSQL 16，部署在北京地域。
> 搜索关于数据库部署的记忆。
> 列出我所有的记忆。

通过Qoder接入

说明

MCP工具仅在Qoder的Agent模式下可用。

接入方式

方式一：通过控制台快速接入

打开Qoder Settings。macOS按Shift+Command+,，Windows按Ctrl+Shift+,。
导航至MCP服务 > 我的服务 > + 添加。

选择通过配置添加，粘贴以下JSON：

{
  "mem0": {
    "type": "http",
    "url": "http://<host>:<port>/mcp",
    "headers": {
      "Authorization": "Token ${MEM0_API_KEY:-apikey}"
    }
  }
}

在项目根目录的.env文件中设置API Key：
```
MEM0_API_KEY=your-api-key
```

方式二：通过配置文件接入

Qoder支持三种作用域的配置文件，其路径与推荐用途如下：

作用域	路径	是否建议提交Git
用户级（全局）	`~/.qoder/settings.json`	—
项目级（共享）	`<project>/.mcp.json`	是
项目级（本地）	`<project>/.qoder/settings.local.json`	否（适合存放密钥）

项目级（共享）配置示例：在项目根目录创建.mcp.json：

{
  "mcpServers": {
    "mem0": {
      "type": "http",
      "url": "http://<host>:<port>/mcp",
      "headers": {
        "Authorization": "Token ${MEM0_API_KEY:-apikey}"
      }
    }
  }
}

项目级（本地）配置示例：在.qoder/settings.local.json中直接写入密钥（不提交Git）：

{
  "mcpServers": {
    "mem0": {
      "type": "http",
      "url": "http://<host>:<port>/mcp",
      "headers": {
        "Authorization": "Token your-actual-api-key"
      }
    }
  }
}

说明

Qoder使用的顶层键名是mcpServers，与VS Code的servers格式不同，请勿混用。

使用示例

> 把当前项目的技术栈存入记忆：Python 3.12 + FastAPI + PolarDB。
> 搜索关于PolarDB配置的记忆。
> 获取user_id为"dev_team"的所有记忆。

通过Hermes Agent接入

适用版本：Hermes Agent 0.17及以上（内置MCP Client，依赖mcp==1.26.0）。

接入方式

方式一：交互式添加

执行以下命令，通过交互式引导完成添加：

hermes mcp add mem0 --url "http://<host>:<port>/mcp"

命令会自动完成以下操作：

提示输入API Key，并保存到~/.hermes/.env。
连接PolarDB记忆管理服务端验证连接，并发现可用的MCP工具。
将配置写入~/.hermes/config.yaml。

启动Hermes即可使用：

hermes

方式二：YAML配置文件

存放API Key：

echo 'MEM0_API_KEY=your-api-key' >> ~/.hermes/.env

编辑~/.hermes/config.yaml：

mcp_servers:
  mem0:
    url: "http://<host>:<port>/mcp"
    headers:
      Authorization: "Token ${MEM0_API_KEY}"
    timeout: 180
    connect_timeout: 60

验证连接：
```
hermes mcp test mem0
```

说明

Hermes环境变量仅支持${VAR_NAME}语法，不支持${VAR:-default}默认值写法。

高级配置

如需自定义超时时间、心跳保活、工具过滤或采样能力，可参考以下配置：

mcp_servers:
  mem0:
    url: "http://<host>:<port>/mcp"
    headers:
      Authorization: "Token ${MEM0_API_KEY}"
    timeout: 180
    connect_timeout: 60
    keepalive_interval: 60    # 心跳保活间隔，单位为秒
    tools:
      include: ["add_memory", "search_memory", "get_all_memories"]
    sampling:
      enabled: true
      model: "gpt-4"
      max_tokens_cap: 4096

管理命令

命令	说明
`hermes mcp list`	查看已配置的MCP服务。
`hermes mcp test mem0`	测试PolarDB记忆管理的连接状态。
`hermes mcp remove mem0`	移除已配置的PolarDB记忆管理 MCP服务。

使用示例

> 记住我下周要去北京出差。
> 搜索我的出行计划。
> 列出所有记忆。

通过Python MCP SDK接入（高级用法）

若您需要在自定义Agent中精细控制MCP连接与工具调用，可使用Python MCP SDK。

安装依赖

pip install "mcp>=1.0" httpx

运行示例

设置API Key并运行示例脚本：

export MEM0_API_KEY="your-api-key"
python mcp_client_example.py
python mcp_client_example.py --url http://<host>:<port>/mcp
python mcp_client_example.py --user-id my_agent_001

代码集成示例

以下示例展示如何在自定义Agent中调用记忆管理的add_memory、search_memory等工具：

import asyncio
from mcp_client_example import add_memory, search_memory, get_all_memories


async def main():
    user_id = "my_agent_001"

    await add_memory(
        user_id=user_id,
        messages=[
            {"role": "user", "content": "我的项目使用PolarDB。"},
            {"role": "assistant", "content": "好的，已记录。"}
        ]
    )

    results = await search_memory(user_id=user_id, query="数据库")
    print(results)


asyncio.run(main())

常用MCP工具参考

接入成功后，AI助手会根据对话内容自动选择合适的工具，通常您无需记忆工具名称。以下工具列表主要供开发者在自定义Agent时参考。

工具名	功能说明
`add_memory_v1_memories_post`	添加记忆。
`search_memories_v2_memories_search_post`	搜索记忆。
`get_all_memories_v2_memories_post`	获取所有记忆。
`delete_memory_v1_memories__memory_id__delete`	删除记忆。
`merge_memories_v1_memories_merge_post`	合并记忆。
`extract_user_profile_v1_profile_extract_post`	抽取用户画像。

说明

v2接口的filters为必填字段，user_id必须放在filters字典内，详见下方常见问题。

常见问题

配置后看不到MCP工具怎么办？
请按以下顺序排查：
1. 确认环境变量MEM0_API_KEY已正确设置。
2. 测试客户端到PolarDB记忆管理连接地址的网络连通性，并确认客户端所在IP已加入应用白名单。
3. 按客户端类型查看连接状态：
  - Claude Code在交互界面输入/mcp。
  - Qoder查看Output面板的MCP日志。
  - Hermes Agent执行hermes mcp test mem0。
请求返回401 Unauthorized怎么办？
认证头格式必须是Token <your-api-key>，不能使用Bearer。请确认API Key正确且未过期。
调用工具时报filters is a required property怎么办？
v2接口要求携带filters字段，user_id必须放在filters字典内。示例：
```
{
  "query": "搜索内容",
  "filters": {"user_id": "your_user_id"}
}
```
Python SDK偶尔收到400错误怎么办？
服务端多Worker部署下，session清理请求可能命中不同Worker。工具调用本身已成功，示例脚本通过Python的except*语法安全忽略此类错误，不影响记忆存储与检索的实际结果。