diff --git a/start-mcp-aliyun-agentloop-memory/hook/index.js b/start-mcp-aliyun-agentloop-memory/hook/index.js new file mode 100644 index 0000000..099f7a5 --- /dev/null +++ b/start-mcp-aliyun-agentloop-memory/hook/index.js @@ -0,0 +1,12 @@ +async function preInit(inputObj) { + +} + +async function postInit(inputObj) { + +} + +module.exports = { + postInit, + preInit +} diff --git a/start-mcp-aliyun-agentloop-memory/publish.yaml b/start-mcp-aliyun-agentloop-memory/publish.yaml new file mode 100644 index 0000000..a3c24f7 --- /dev/null +++ b/start-mcp-aliyun-agentloop-memory/publish.yaml @@ -0,0 +1,48 @@ +Edition: 3.0.0 +Type: Project +Name: mcp-agentloop-memory +Version: 0.1.0 +Provider: + - 阿里云 # 取值内容参考:https://api.devsapp.cn/v3/common/args.html +Description: AgentLoop Memory MCP Server +HomePage: https://github.com/devsapp/fcai-mcp-servers/tree/main/start-mcp-aliyun-agentloop-memory +Tags: #标签详情 + - MCP + - Python +Category: MCP服务 # 取值内容参考:https://api.devsapp.cn/v3/common/args.html +Service: # 使用的服务 + 函数计算: # 取值内容参考:https://api.devsapp.cn/v3/common/args.html + Authorities: #权限描述 + - AliyunFCFullAccess # 所需要的权限,例如AliyunFCFullAccess +Organization: 阿里云函数计算(FC) # 所属组织 +Effective: Public # 是否公开,取值:Public,Private,Organization +Parameters: + type: object + additionalProperties: false # 不允许增加其他属性 + required: # 必填项 + - region + properties: + region: + title: 地域 + type: string + default: cn-hangzhou + description: 创建应用所在的地区 + enum: + - cn-beijing + - cn-hangzhou + - cn-shanghai + - cn-shenzhen + - ap-southeast-1 + - us-west-1 + serviceRole: + title: 函数计算访问 CMS 角色 + type: string + default: "AliyunFCDefaultRole" + pattern: "^acs:ram::[0-9]*:role/.*$" + description: "函数中需要基于此角色访问 CMS" + required: true + x-role: + name: AliyunFCDefaultRole + service: FC + authorities: + - AliyunCloudMonitorFullAccess \ No newline at end of file diff --git a/start-mcp-aliyun-agentloop-memory/readme.md b/start-mcp-aliyun-agentloop-memory/readme.md new file mode 100644 index 0000000..023a9b9 --- /dev/null +++ b/start-mcp-aliyun-agentloop-memory/readme.md @@ -0,0 +1,187 @@ + +> 注:当前项目为 Serverless Devs 应用,由于应用中会存在需要初始化才可运行的变量(例如应用部署地区、函数名等等),所以**不推荐**直接 Clone 本仓库到本地进行部署或直接复制 s.yaml 使用,**强烈推荐**通过 `s init ${模版名称}` 的方法或应用中心进行初始化,详情可参考[部署 & 体验](#部署--体验) 。 + +# mcp-agentloop-memory 帮助文档 + + + +AgentLoop Memory MCP Server + + + + +## 资源准备 + +使用该项目,您需要有开通以下服务并拥有对应权限: + + + + + +| 服务/业务 | 权限 | 相关文档 | +| --- | --- | --- | +| 函数计算 | AliyunFCFullAccess | [帮助文档](https://help.aliyun.com/product/2508973.html) [计费文档](https://help.aliyun.com/document_detail/2512928.html) | + + + + + + + + + + + + + + + +## 部署 & 体验 + + + +- :fire: 通过 [云原生应用开发平台 CAP](https://functionai.console.aliyun.com/template-detail?template=mcp-agentloop-memory) ,[![Deploy with Severless Devs](https://img.alicdn.com/imgextra/i1/O1CN01w5RFbX1v45s8TIXPz_!!6000000006118-55-tps-95-28.svg)](https://functionai.console.aliyun.com/template-detail?template=mcp-agentloop-memory) 该应用。 + + + + + + + +## 案例介绍 + + + +### alibabacloud-agentloop-memory-mcp-server + +阿里云 AgentLoop MemoryStore 的 MCP Server 实现,为 AI Agent 提供长期记忆管理能力,支持通过 MCP 协议(SSE 传输)进行记忆的增删改查和语义搜索。 + +#### AgentLoop MemoryStore + +[AgentLoop MemoryStore](https://www.alibabacloud.com/) 是阿里云提供的全托管 AI Agent 长期记忆服务。它为 AI Agent 提供智能记忆层,使其能够跨会话记住用户偏好、持续学习并实现个性化交互,适用于智能客服、个人助理、教育辅导等场景。 + +**核心特性:** + +- **多维度记忆**:自动从对话中提取用户偏好、事实陈述、会话摘要等结构化记忆,支持自定义提取策略 +- **分层检索**:L1 混合检索 → L2 Rerank 精排 → L3 Agentic Search,兼顾召回广度与精度 +- **异步提取**:记忆处理异步执行,不阻塞 Agent 主流程,支持弹性扩缩容 +- **全托管**:无需搭建向量数据库或维护存储实例,开通即用 +- **可观测**:内置监控大盘,覆盖检索延迟、Token 消耗、存储量等核心指标 + +本案例将 AgentLoop MemoryStore 封装为标准 [MCP](https://modelcontextprotocol.io/) Server,支持 Cursor、Claude Desktop 等 MCP 客户端直接接入。 + + +#### 安装 + +```bash +pip install alibabacloud-agentloop-memory-mcp-server +``` + +#### 快速开始 + +##### 1. 配置环境变量 + +```bash +export ALIBABA_CLOUD_ACCESS_KEY_ID=your_access_key_id +export ALIBABA_CLOUD_ACCESS_KEY_SECRET=your_access_key_secret +export ALIBABA_CLOUD_REGION_ID=cn-hangzhou +export ALIBABA_CLOUD_WORKSPACE=your_workspace_name +export ALIBABA_CLOUD_MEMORY_STORE=your_memory_store_name +``` + +##### 2. 启动服务 + +```bash +# 使用 python -m 启动 +python -m mcp_server_agentloop_memory + +# 或使用命令行入口 +alibabacloud-agentloop-memory-mcp-server + +# 指定参数启动 +python -m mcp_server_agentloop_memory \ + --access-key-id \ + --access-key-secret \ + --region-id cn-hangzhou \ + --workspace \ + --memory-store \ + --port 8080 +``` + +##### 3. 连接 MCP Client + +服务启动后,MCP Client 通过 SSE 连接: + +``` +GET http://localhost:8080/mcp/{client_name}/sse/{user_id} +``` + +- `client_name`:客户端标识(如 `cursor`、`my-agent`),映射为 `agent_id` +- `user_id`:用户标识,用于隔离不同用户的记忆数据 + +#### CLI 参数 + +| 参数 | 环境变量 | 默认值 | 说明 | +|------|---------|--------|------| +| `--access-key-id` | `ALIBABA_CLOUD_ACCESS_KEY_ID` | - | 阿里云 AccessKey ID | +| `--access-key-secret` | `ALIBABA_CLOUD_ACCESS_KEY_SECRET` | - | 阿里云 AccessKey Secret | +| `--region-id` | `ALIBABA_CLOUD_REGION_ID` | `cn-hangzhou` | 阿里云区域 | +| `--workspace` | `ALIBABA_CLOUD_WORKSPACE` | - | Workspace 名称 | +| `--memory-store` | `ALIBABA_CLOUD_MEMORY_STORE` | - | Memory Store 名称 | +| `--host` | - | `0.0.0.0` | 监听地址 | +| `--port` | - | `8080` | 监听端口 | +| `--log-level` | - | `INFO` | 日志级别 | + +#### MCP Tools + +| 工具名 | 参数 | 说明 | +|--------|------|------| +| `add_memories` | `text: str` | 添加记忆。当用户分享个人信息、偏好或要求记住某些内容时调用 | +| `search_memory` | `query: str` | 语义搜索记忆。用户提问时自动调用,返回按相关度排序的记忆 | +| `list_memories` | 无 | 列出当前用户的所有记忆 | +| `delete_memories` | `memory_ids: list[str]` | 按 ID 删除指定记忆 | +| `delete_all_memories` | 无 | 删除当前用户的所有记忆 | + +#### 权限要求 + +需要阿里云 RAM 用户具有 AgentLoop MemoryStore 相关 API 的访问权限。获取和管理 AccessKey 请参考[阿里云 AccessKey 管理](https://help.aliyun.com/document_detail/53045.html)。 + +#### 开发 + +```bash +# 安装开发依赖 +pip install -e ".[dev]" + +# 运行测试(需要配置环境变量) +pytest tests/ -v +``` + + + + + + + + + + + + +## 使用流程 + + + +部署完成拿到 URL 后,准备好支持 SSE 的 MCP Client,通过 SSETransport 进行连接。 + + + +## 二次开发指南 + + + + + + + + + diff --git a/start-mcp-aliyun-agentloop-memory/src/build.yaml b/start-mcp-aliyun-agentloop-memory/src/build.yaml new file mode 100644 index 0000000..874d776 --- /dev/null +++ b/start-mcp-aliyun-agentloop-memory/src/build.yaml @@ -0,0 +1,11 @@ +mcp-agentloop-memory: + default: + rootPath: ./code + languages: + - python3.12 + cache: + paths: + - "~/.cache" + steps: + - run: mkdir -p python + - run: pip install -r requirements.txt -t ./python \ No newline at end of file diff --git a/start-mcp-aliyun-agentloop-memory/src/code/requirements.txt b/start-mcp-aliyun-agentloop-memory/src/code/requirements.txt new file mode 100644 index 0000000..d16e2e2 --- /dev/null +++ b/start-mcp-aliyun-agentloop-memory/src/code/requirements.txt @@ -0,0 +1 @@ +alibabacloud-agentloop-memory-mcp-server==0.1.3 \ No newline at end of file diff --git a/start-mcp-aliyun-agentloop-memory/src/mcp-schema.json b/start-mcp-aliyun-agentloop-memory/src/mcp-schema.json new file mode 100644 index 0000000..189b8bc --- /dev/null +++ b/start-mcp-aliyun-agentloop-memory/src/mcp-schema.json @@ -0,0 +1,81 @@ +{ + "tools": [ + { + "inputSchema": { + "type": "object", + "title": "add_memoriesArguments", + "properties": { + "text": { + "description": "The text content to store as a memory. This can be personal info, preferences, or anything the user wants to remember.", + "title": "Text", + "type": "string" + } + }, + "required": [ + "text" + ] + }, + "name": "add_memories", + "description": "Add a new memory. Called when the user shares personal info, preferences, or asks you to remember something.\n\n ## 功能概述\n\n 将用户提供的文本内容存储为新的记忆。系统会自动对文本进行推理提取(infer=True),从中识别出关键信息并存储。\n\n ## 使用场景\n\n - 当用户分享个人信息时(如姓名、职业、兴趣爱好等)\n - 当用户明确要求「记住这个」时\n - 当用户表达偏好或习惯时\n\n ## 返回数据结构\n\n 返回的结果包含:\n - request_id: 请求唯一标识\n - results: 记忆存储结果列表,每项包含 event_id、message、status\n\n ## 使用示例\n\n - \"记住我喜欢喝咖啡\"\n - \"我的名字是张三\"\n - \"我对花生过敏\"\n\n Args:\n text: 要存储为记忆的文本内容\n\n Returns:\n 包含 request_id 和 results 列表的 JSON 字符串\n " + }, + { + "inputSchema": { + "type": "object", + "title": "search_memoryArguments", + "properties": { + "query": { + "description": "The search query to find relevant memories.", + "title": "Query", + "type": "string" + } + }, + "required": [ + "query" + ] + }, + "name": "search_memory", + "description": "Search through stored memories. Called whenever the user asks anything.\n\n ## 功能概述\n\n 通过语义搜索查找与查询内容相关的记忆,返回最相关的记忆条目以及相关的关系图谱数据。\n\n ## 使用场景\n\n - 当用户提问时,搜索相关记忆以提供个性化回答\n - 当需要回忆用户之前提到的偏好或信息时\n - 当需要获取用户的历史上下文时\n\n ## 返回数据结构\n\n 返回的结果包含:\n - results: 记忆列表,每项包含 id、memory、score、user_id、agent_id、created_at、updated_at、hash、metadata\n - relations: 关系图谱列表,每项包含 source、relationship、destination\n\n ## 使用示例\n\n - \"我之前说过我喜欢什么?\"\n - \"我的饮食偏好是什么?\"\n - \"你还记得我的名字吗?\"\n\n Args:\n query: 用于搜索记忆的查询文本\n\n Returns:\n 包含 results 和 relations 的 JSON 字符串\n " + }, + { + "inputSchema": { + "type": "object", + "title": "list_memoriesArguments", + "properties": {}, + "required": [] + }, + "name": "list_memories", + "description": "List all memories for the current user.\n\n ## 功能概述\n\n 列出当前用户的所有已存储记忆,不需要任何查询参数。用户身份通过 SSE 连接的 URL 路径自动注入。\n\n ## 使用场景\n\n - 当用户想查看所有已存储的记忆时\n - 当需要展示记忆概览时\n - 当用户问「你都记住了什么」时\n\n ## 返回数据结构\n\n 返回的结果包含:\n - results: 记忆列表,每项包含 id、memory、score、user_id、agent_id、created_at、updated_at、hash、metadata\n\n ## 使用示例\n\n - \"你都记住了哪些关于我的信息?\"\n - \"列出所有记忆\"\n - \"展示我的记忆列表\"\n\n Returns:\n 包含 results 列表的 JSON 字符串\n " + }, + { + "inputSchema": { + "type": "object", + "title": "delete_memoriesArguments", + "properties": { + "memory_ids": { + "description": "List of memory IDs to delete.", + "title": "Memory Ids", + "type": "array", + "items": { + "type": "string" + } + } + }, + "required": [ + "memory_ids" + ] + }, + "name": "delete_memories", + "description": "Delete specific memories by their IDs.\n\n ## 功能概述\n\n 根据记忆 ID 列表批量删除指定的记忆条目。支持一次删除多条记忆,并返回删除结果统计。\n\n ## 使用场景\n\n - 当用户要求删除某条特定记忆时\n - 当用户要求忘记某些信息时\n - 当需要清理过时或错误的记忆时\n\n ## 返回数据结构\n\n 返回删除结果的文本描述,包含:\n - 成功删除的数量\n - 如有错误,附带错误详情\n\n ## 使用示例\n\n - \"删除这条记忆:abc123\"\n - \"忘记我之前说的那个偏好\"\n\n Args:\n memory_ids: 要删除的记忆 ID 列表\n\n Returns:\n 删除操作的结果描述字符串\n " + }, + { + "inputSchema": { + "type": "object", + "title": "delete_all_memoriesArguments", + "properties": {}, + "required": [] + }, + "name": "delete_all_memories", + "description": "Delete all memories for the current user.\n\n ## 功能概述\n\n 删除当前用户的所有记忆数据。这是一个不可逆操作,执行后用户的全部记忆将被永久清除。\n\n ## 使用场景\n\n - 当用户明确要求清除所有记忆时\n - 当用户要求「忘记关于我的一切」时\n - 当需要重置用户记忆状态时\n\n ## 返回数据结构\n\n 返回操作结果的文本描述\n\n ## 使用示例\n\n - \"清除你记住的所有关于我的信息\"\n - \"忘记关于我的一切\"\n - \"删除所有记忆\"\n\n Returns:\n 操作结果的描述字符串\n " + } + ] +} diff --git a/start-mcp-aliyun-agentloop-memory/src/readme.md b/start-mcp-aliyun-agentloop-memory/src/readme.md new file mode 100644 index 0000000..023a9b9 --- /dev/null +++ b/start-mcp-aliyun-agentloop-memory/src/readme.md @@ -0,0 +1,187 @@ + +> 注:当前项目为 Serverless Devs 应用,由于应用中会存在需要初始化才可运行的变量(例如应用部署地区、函数名等等),所以**不推荐**直接 Clone 本仓库到本地进行部署或直接复制 s.yaml 使用,**强烈推荐**通过 `s init ${模版名称}` 的方法或应用中心进行初始化,详情可参考[部署 & 体验](#部署--体验) 。 + +# mcp-agentloop-memory 帮助文档 + + + +AgentLoop Memory MCP Server + + + + +## 资源准备 + +使用该项目,您需要有开通以下服务并拥有对应权限: + + + + + +| 服务/业务 | 权限 | 相关文档 | +| --- | --- | --- | +| 函数计算 | AliyunFCFullAccess | [帮助文档](https://help.aliyun.com/product/2508973.html) [计费文档](https://help.aliyun.com/document_detail/2512928.html) | + + + + + + + + + + + + + + + +## 部署 & 体验 + + + +- :fire: 通过 [云原生应用开发平台 CAP](https://functionai.console.aliyun.com/template-detail?template=mcp-agentloop-memory) ,[![Deploy with Severless Devs](https://img.alicdn.com/imgextra/i1/O1CN01w5RFbX1v45s8TIXPz_!!6000000006118-55-tps-95-28.svg)](https://functionai.console.aliyun.com/template-detail?template=mcp-agentloop-memory) 该应用。 + + + + + + + +## 案例介绍 + + + +### alibabacloud-agentloop-memory-mcp-server + +阿里云 AgentLoop MemoryStore 的 MCP Server 实现,为 AI Agent 提供长期记忆管理能力,支持通过 MCP 协议(SSE 传输)进行记忆的增删改查和语义搜索。 + +#### AgentLoop MemoryStore + +[AgentLoop MemoryStore](https://www.alibabacloud.com/) 是阿里云提供的全托管 AI Agent 长期记忆服务。它为 AI Agent 提供智能记忆层,使其能够跨会话记住用户偏好、持续学习并实现个性化交互,适用于智能客服、个人助理、教育辅导等场景。 + +**核心特性:** + +- **多维度记忆**:自动从对话中提取用户偏好、事实陈述、会话摘要等结构化记忆,支持自定义提取策略 +- **分层检索**:L1 混合检索 → L2 Rerank 精排 → L3 Agentic Search,兼顾召回广度与精度 +- **异步提取**:记忆处理异步执行,不阻塞 Agent 主流程,支持弹性扩缩容 +- **全托管**:无需搭建向量数据库或维护存储实例,开通即用 +- **可观测**:内置监控大盘,覆盖检索延迟、Token 消耗、存储量等核心指标 + +本案例将 AgentLoop MemoryStore 封装为标准 [MCP](https://modelcontextprotocol.io/) Server,支持 Cursor、Claude Desktop 等 MCP 客户端直接接入。 + + +#### 安装 + +```bash +pip install alibabacloud-agentloop-memory-mcp-server +``` + +#### 快速开始 + +##### 1. 配置环境变量 + +```bash +export ALIBABA_CLOUD_ACCESS_KEY_ID=your_access_key_id +export ALIBABA_CLOUD_ACCESS_KEY_SECRET=your_access_key_secret +export ALIBABA_CLOUD_REGION_ID=cn-hangzhou +export ALIBABA_CLOUD_WORKSPACE=your_workspace_name +export ALIBABA_CLOUD_MEMORY_STORE=your_memory_store_name +``` + +##### 2. 启动服务 + +```bash +# 使用 python -m 启动 +python -m mcp_server_agentloop_memory + +# 或使用命令行入口 +alibabacloud-agentloop-memory-mcp-server + +# 指定参数启动 +python -m mcp_server_agentloop_memory \ + --access-key-id \ + --access-key-secret \ + --region-id cn-hangzhou \ + --workspace \ + --memory-store \ + --port 8080 +``` + +##### 3. 连接 MCP Client + +服务启动后,MCP Client 通过 SSE 连接: + +``` +GET http://localhost:8080/mcp/{client_name}/sse/{user_id} +``` + +- `client_name`:客户端标识(如 `cursor`、`my-agent`),映射为 `agent_id` +- `user_id`:用户标识,用于隔离不同用户的记忆数据 + +#### CLI 参数 + +| 参数 | 环境变量 | 默认值 | 说明 | +|------|---------|--------|------| +| `--access-key-id` | `ALIBABA_CLOUD_ACCESS_KEY_ID` | - | 阿里云 AccessKey ID | +| `--access-key-secret` | `ALIBABA_CLOUD_ACCESS_KEY_SECRET` | - | 阿里云 AccessKey Secret | +| `--region-id` | `ALIBABA_CLOUD_REGION_ID` | `cn-hangzhou` | 阿里云区域 | +| `--workspace` | `ALIBABA_CLOUD_WORKSPACE` | - | Workspace 名称 | +| `--memory-store` | `ALIBABA_CLOUD_MEMORY_STORE` | - | Memory Store 名称 | +| `--host` | - | `0.0.0.0` | 监听地址 | +| `--port` | - | `8080` | 监听端口 | +| `--log-level` | - | `INFO` | 日志级别 | + +#### MCP Tools + +| 工具名 | 参数 | 说明 | +|--------|------|------| +| `add_memories` | `text: str` | 添加记忆。当用户分享个人信息、偏好或要求记住某些内容时调用 | +| `search_memory` | `query: str` | 语义搜索记忆。用户提问时自动调用,返回按相关度排序的记忆 | +| `list_memories` | 无 | 列出当前用户的所有记忆 | +| `delete_memories` | `memory_ids: list[str]` | 按 ID 删除指定记忆 | +| `delete_all_memories` | 无 | 删除当前用户的所有记忆 | + +#### 权限要求 + +需要阿里云 RAM 用户具有 AgentLoop MemoryStore 相关 API 的访问权限。获取和管理 AccessKey 请参考[阿里云 AccessKey 管理](https://help.aliyun.com/document_detail/53045.html)。 + +#### 开发 + +```bash +# 安装开发依赖 +pip install -e ".[dev]" + +# 运行测试(需要配置环境变量) +pytest tests/ -v +``` + + + + + + + + + + + + +## 使用流程 + + + +部署完成拿到 URL 后,准备好支持 SSE 的 MCP Client,通过 SSETransport 进行连接。 + + + +## 二次开发指南 + + + + + + + + + diff --git a/start-mcp-aliyun-agentloop-memory/src/s.yaml b/start-mcp-aliyun-agentloop-memory/src/s.yaml new file mode 100644 index 0000000..4eacae4 --- /dev/null +++ b/start-mcp-aliyun-agentloop-memory/src/s.yaml @@ -0,0 +1,22 @@ +edition: 3.0.0 +name: mcp-agentloop-memory +access: "{{ access }}" + +vars: + region: "{{ region }}" + +resources: + mcp-agentloop-memory: + component: fcai-mcp-server + props: + region: ${vars.region} + description: mcp server deployed by devs + transport: sse + port: 8080 + ssePath: /mcp/myagent/sse/user1 + runtime: python3.12 + startCommand: 'python3 -m mcp_server_agentloop_memory' + cpu: 0.5 + memorySize: 512 + enableAuth: true + role: {{ serviceRole }} diff --git a/start-mcp-aliyun-agentloop-memory/src/variable.yaml b/start-mcp-aliyun-agentloop-memory/src/variable.yaml new file mode 100644 index 0000000..57eb3a6 --- /dev/null +++ b/start-mcp-aliyun-agentloop-memory/src/variable.yaml @@ -0,0 +1,20 @@ +services: # 服务变量 + mcp-agentloop-memory: # 对应 s.yaml 中 resources 中的某个 key, 代表某个服务 + ALIBABA_CLOUD_REGION_ID: + title: AgentLoop MemoryStore 地域ID + type: string + default: "" + description: "" + required: true + ALIBABA_CLOUD_WORKSPACE: + title: AgentLoop Workspace + type: string + default: "" + description: "" + required: true + ALIBABA_CLOUD_MEMORY_STORE: + title: AgentLoop MemoryStore + type: string + default: "" + description: "" + required: true \ No newline at end of file diff --git a/start-mcp-aliyun-agentloop-memory/version.md b/start-mcp-aliyun-agentloop-memory/version.md new file mode 100644 index 0000000..4ee89d2 --- /dev/null +++ b/start-mcp-aliyun-agentloop-memory/version.md @@ -0,0 +1,2 @@ +- 初始化项目 +- 测试项目模板 \ No newline at end of file