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

阿里云大数据AI技术
0 阅读7分钟

作者： 阿里云计算平台AI搜索团队 

在2026年 OpenClaw 大行其道的当下，OpenClaw 原生的记忆组件基于本地存储，不支持跨设备同步和跨会话记忆，其痛点显著。阿里云计算平台AI搜索团队通过集成发布的 Agentic Memory API 作为云端智能记忆服务，灵活对接 OpenClaw 提供持久化的长记忆能力、语义检索和技能管理功能。彻底解决 OpenClaw 本地存储记忆不智能的痛点。

方案简介

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

快速部署

1. 在 OpenClaw（或者 JVSClaw 等兼容版 agent）对话框内输入以下指令安装插件：

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

2. 然后根据提示输入配置信息即可。

3. 安装完成后，自动重启openclaw gateway，需要等待一分钟左右。

方案架构

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

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

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

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

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

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

方案优势对比

维度OpenClaw原生方案Agentic Memory方案
存储后端本地SQLite/LanceDBAgentic Memory API云端服务
数据持久化本地文件云端持久化
跨设备同步不支持支持
跨会话记忆不支持支持
事实提取需本地LLM处理服务端自动提取
向量化与检索需本地嵌入模型服务端自动完成
技能管理不支持支持搜索、获取、上传、更新
异步存储不支持支持异步任务，可查询状态
本地依赖需要原生依赖仅需Node.js内置fetch

实践步骤

（一）操作流程

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

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

  2. 在控制台左侧导航栏选择智能问答 > API Key管理，获取以下信息：

    • 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 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（需支持内置 fetch() ）。

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

该命令从 npm 公共注册表下载并安装插件。如果默认 npm registry 不是公共注册表（如使用了内部私有 registry ），可先手动下载插件包再本地安装：

npm pack @alicloud-ai-search/openclaw-memory --registry https://registry.npmjs.org
openclaw plugins install ./alicloud-ai-search-openclaw-memory-0.1.0.tgz

步骤三：配置插件参数

编辑 ~/.openclaw/openclaw.json，在 plugins.entries 下添加 openclaw-memory 配置：

{
  "plugins": {
    "entries": {
      "openclaw-memory": {
        "enabled": true,
        "config": {
          "baseUrl": "http://<workspace-id>.platform-cn-shanghai.opensearch.aliyuncs.com",
          "workspaceName": "default",
          "apiKey": "YOUR_API_KEY_HERE"
        }
      }
    }
  }
}

将 <workspace-id> 替换为步骤一中获取的工作空间标识符，workspaceName、YOUR_API_KEY_HERE 替换为实际使用的空间名称和 API Key。

配置参数说明：

参数类型默认值是否必填说明
baseUrlstring是Agentic Memory API服务地址，从AI搜索开放平台控制台获取
workspaceNamestring是工作空间名称
apiKeystring是API Key，用于接口认证
serviceIdstringagentic-memory否记忆服务的Service ID
userIdstring如果不配置，将自动生成一个uuid，保存到：~/.openclaw/autogen-userid.txt。配置后自动生成的userid值被覆盖。否用户标识，用于区分不同用户的记忆
agentIdstring""否Agent标识，用于将记忆和技能关联到特定Agent
autoRecallMemorybooleanfalse否是否在Agent执行前自动召回相关记忆
autoCaptureMemorybooleanfalse否是否在Agent执行后自动捕获对话并存储为记忆
autoRecallSkillbooleanfalse否是否在自动召回时同时检索技能
autoCaptureSkillbooleanfalse否是否自动从对话中捕获技能（即将推出）
recallLimitnumber5否每次自动召回的最大记忆数量

步骤四：启动或重启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>

Agent工具

在对话中可以直接触发 Agent 的记忆管理工具：memory_recall、memory_store、memory_update、memory_forget、memory_get

工作原理

自动召回流程

当 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. 过滤掉以下内容：

    • 长度少于50字符的短消息

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

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

    • 临时会话的消息

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

REST API接口

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

方法路径说明
GET{prefix}/health健康检查
POST{prefix}/search搜索记忆和技能
POST{prefix}/memories存储记忆（异步）
PUT{prefix}/memories/:id更新记忆
GET{prefix}/:id根据ID获取记忆或技能
DELETE{prefix}/:id删除记忆或技能
GET{prefix}/tasks/:task_id查询异步任务状态
PUT{prefix}/skills/:id更新技能

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

常见问题

插件注册后日志无输出

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

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

搜索返回空结果

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

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

  • 查看 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
avatar
文章
阅读
粉丝