基于Agentic Memory API实现OpenClaw长记忆增强

方案简介

基于Agentic Memory实现OpenClaw长记忆增强能力，构建长短记忆、情景、语义的多层记忆体系。通过向量混合云存储，实现跨会话信息持久化及智能检索巩固，突破上下文限制，赋予Agent长期个性化记忆能力，显著提升交互连贯性与用户理解深度。

快速部署

在OpenClaw（或者阿里云JVSClaw等兼容版Agent产品）对话框内输入以下Prompt指令，安装插件：

请根据https://help.aliyun.com/zh/open-search/search-platform/use-cases/best-practice-agentic-memory-openclaw 文档安装插件

方案架构

整体方案架构包含以下核心流程：

1. 提取（Extract）：Agentic Memory从用户输入中提取关键信息，识别需要记忆的内容(Facts, Skills)。

2. 向量化（Embed）：使用文本嵌入模型将提取的信息转换为高维向量。

3. 存储（Store）：将向量数据和文本信息写入Elasticsearch。

4. 检索（Retrieve）：当用户发起新请求时，在Elasticsearch中召回相关Facts, Skills。

5. 融合（Fuse）：将检索到的记忆与当前上下文融合，增强LLM的响应质量。

方案优势对比

操作流程

步骤一：开通Agentic Memory API服务并获取连接信息

1. 登录AI搜索开放平台控制台，开通Agentic Memory API服务（开通AI搜索开放平台时自动开通）。

2. 在AI搜索开放平台控制台左侧导航栏选择API Keys，获取以下信息：

   • API服务地址（baseUrl）：格式为http://<workspace-id>.platform-cn-shanghai.opensearch.aliyuncs.com，其中<workspace-id>为工作空间标识符（如default-xxx），可在控制台的API Key管理页面查看。

   • API Key：用于接口认证的Bearer Token。

   • Workspace Name：用于接口认证，从右上角空间管理获取。

3. 通过健康检查接口验证服务状态：

   curl -H "Authorization: Bearer <YOUR_API_KEY>" http://<baseUrl>/v3/openapi/workspaces/<workspace_name>/memory/agentic-memory/health

   预期返回：

   {
     "request_id": "...",
     "latency": 0,
     "status": "OK",
     "result": {
       "status": "healthy"
     }
   }

步骤二：安装插件

运行以下命令安装OpenClaw记忆插件。需要已安装OpenClaw且Node.js版本 >= 18。

openclaw plugins install @alicloud-ai-search/openclaw-memory

步骤三：配置插件参数

编辑~/.openclaw/openclaw.json，需要完成两部分配置：

1. 在plugins.entries下添加openclaw-memory，用于配置自动召回/捕获等行为及访问凭据。

2. 在mcp.servers下添加agentic-memory，用于以MCP Server的方式接入记忆、技能、知识库相关工具。

{
  "plugins": {
    "entries": {
      "openclaw-memory": {
        "enabled": true,
        "config": {
          "baseUrl": "YOUR_BASE_URL_HERE",
          "workspaceName": "YOUR_WORKSPACE_NAME_HERE",
          "apiKey": "YOUR_API_KEY_HERE",
          "autoRecallMemory": true,
          "autoCaptureMemory": true
        },
        "hooks": {
          "allowConversationAccess": true
        }
      }
    }
  },
  "mcp": {
    "servers": {
      "agentic-memory": {
        "url": "YOUR_BASE_URL_HERE/v1/agentic-memory/mcp",
        "transport": "streamable-http",
        "headers": {
          "Authorization": "Bearer YOUR_API_KEY_HERE"
        }
      }
    }
  }
}

将YOUR_BASE_URL_HERE、YOUR_WORKSPACE_NAME_HERE、YOUR_API_KEY_HERE替换为实际使用的服务地址、空间名称和API Key。

插件配置参数说明：

MCP Server配置说明（mcp.servers.agentic-memory）：

步骤四：启动或重启Gateway

配置完成后，需要启动（或重启）OpenClaw Gateway使配置生效。

如果Gateway已经在运行，执行重启命令：

openclaw gateway restart

如果是首次配置Gateway（未启动过），需要先设置Gateway模式再启动：

openclaw config set gateway.mode local
openclaw gateway --port 18789

启动成功后，日志中出现以下信息表示插件注册成功：

[openclaw-memory] Plugin registered (autoRecallMemory=true, autoCaptureMemory=true, autoRecallSkill=false, autoCaptureSkill=false, ...)

验证记忆功能

对话测试

在OpenClaw中发送消息测试长记忆功能：

1. 发送：我叫小明，帮我记一下，我下周一早上十点有个会。

2. 等待回复，确认消息已处理。

3. 发送新消息：请介绍一下我。

4. 验证OpenClaw是否能记忆名字和会议信息。

CLI命令

使用CLI命令直接与记忆服务交互：

# 搜索记忆
openclaw mem search "项目架构"

# 搜索记忆并包含技能结果
openclaw mem search "项目架构" --limit 10 --skill

# 根据ID获取记忆详情
openclaw mem get <memory_id>

# 删除指定记忆
openclaw mem forget <memory_id>

# 查询异步存储任务状态
openclaw mem task <task_id>

# 更新记忆
openclaw mem update <id> "new memory content"

MCP工具

新版插件中，记忆、技能、知识库相关工具均通过agentic-memory MCP Server统一对外提供，无需单独注册Agent工具。Gateway启动后，OpenClaw会自动从配置的MCP Server拉取工具列表，在对话中可直接调用记忆搜索、存储、更新、删除以及技能与知识库相关工具。

工作原理

自动召回流程

当autoRecallMemory启用时，插件在before_agent_start事件中自动执行以下操作：

1. 获取用户输入作为搜索查询。

2. 向Agentic Memory API发送搜索请求，检索最多recallLimit条相关记忆。如果autoRecallSkill启用，同时检索相关技能。

3. 将检索结果以XML格式注入到Agent上下文前部：

   <relevant-memories>
   Relevant facts from long-term memory:
   - 用户名为小明
   - 用户下周一早上十点有会议
   
   Relevant skills:
   - skill-name: description of the skill
   </relevant-memories>

临时会话（session key以temp:开头）和启动提示会被自动跳过。

自动捕获流程

当autoCaptureMemory启用时，插件在agent_end事件中自动执行以下操作：

1. 提取对话中的用户和助手消息。

2. 过滤掉以下内容：

   • 包含<relevant-memories>的消息（防止反馈循环）

   • 启动提示（以A new session was started via开头）

   • 临时会话的消息

3. 将过滤后的消息发送到Agentic Memory API进行事实提取和异步存储。

REST API接口

插件通过以下REST接口与Agentic Memory API通信：

{prefix} = {baseUrl}/v3/openapi/workspaces/{workspace_name}/memory/{serviceId}

常见问题

安装过程中找不到插件

如果默认npm registry不是官方源，可能导致搜索不到。可以在安装命令之前指定registry：

npm_config_registry=https://registry.npmjs.org \
openclaw plugins install @alicloud-ai-search/openclaw-memory

插件注册后日志无输出

检查~/.openclaw/openclaw.json中的plugins.slots.memory是否正确指向openclaw-memory，并确认enabled为true。plugins.slots.memory通常在安装插件时自动设置，如果缺失可手动添加：

{
  "plugins": {
    "slots": {
      "memory": "openclaw-memory"
    }
  }
}

搜索返回空结果

• 确认Agentic Memory API服务正常运行（通过健康检查接口验证）。

• 确认已有记忆被存储（通过autoCaptureMemory自动捕获或通过MCP Server提供的记忆存储工具手动存储）。

• 查看OpenClaw日志中以[openclaw-memory]开头的条目，其中包含所有API请求日志。

记忆存储后无法立即检索

记忆存储是异步操作，存储请求提交后会返回task_id。通过openclaw mem task <task_id>查询任务状态，确认存储任务已完成后再进行检索。

自动召回未触发

• 确认autoRecallMemory设置为true。

• 确认当前会话不是临时会话（session key不以temp:开头）。

• 确认用户输入不为空。

首次启动Gateway失败

如果执行openclaw gateway restart返回"Gateway service not loaded"错误，说明Gateway尚未初始化。按以下步骤操作：

openclaw config set gateway.mode local
openclaw gateway --port 18789

MCP工具未生效

• 确认~/.openclaw/openclaw.json中mcp.servers.agentic-memory已配置，且url为{baseUrl}/v1/agentic-memory/mcp、transport为streamable-http。

• 确认headers.Authorization使用Bearer {apiKey}格式，且API Key与插件配置中的一致。

• 配置完成后需执行openclaw gateway restart让MCP Server配置生效。

• 通过curl -X POST -H "Authorization: Bearer <YOUR_API_KEY>" -H "Content-Type: application/json" -H "Accept: application/json, text/event-stream" {baseUrl}/v1/agentic-memory/mcp -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"test","version":"1.0"}}}'验证MCP接入地址连通性。