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

简介

@alicloud-ai-search/openclaw-memory是Agentic Memory针对OpenClaw设计的记忆插件，通过REST API实现语义记忆的存储、检索、更新和遗忘，同时支持技能的搜索、获取和上传。插件本身是一个轻量级HTTP客户端，所有事实提取、向量化和相似度检索均在服务端完成，无需本地安装原生依赖。

方案对比

方案架构

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

• 自动召回（Auto-Recall）：用户发起新请求时，插件自动将用户输入作为查询发送到Agentic Memory API，检索相关记忆和技能，注入到Agent上下文中。

• 自动捕获（Auto-Capture）：Agent执行完成后，插件自动提取对话中的用户和助手消息，发送到Agentic Memory API进行事实提取和存储。

• 主动工具调用（Agent Tools）：Agent可通过五个内置工具（memory_recall、memory_store、memory_update、memory_forget、memory_get）主动管理记忆。

• 技能管理（Skill Management）：支持搜索、获取、上传和更新可复用技能，技能文件可导出到本地供Agent使用。

用户输入
  │
  ├──[Auto-Recall]──→ POST {prefix}/search ──→ Agentic Memory API ──→ 注入相关记忆到上下文
  │
  ▼
Agent 执行
  ├── memory_recall  ──→ POST {prefix}/search        ──→ Agentic Memory API
  ├── memory_store   ──→ POST {prefix}/memories       ──→ Agentic Memory API (异步)
  ├── memory_update  ──→ PUT  {prefix}/memories/:id   ──→ Agentic Memory API
  ├── memory_forget  ──→ DELETE {prefix}/:id           ──→ Agentic Memory API
  └── memory_get     ──→ GET  {prefix}/:id             ──→ Agentic Memory API
  │
  ▼
Agent 完成
  └──[Auto-Capture]──→ POST {prefix}/memories ──→ Agentic Memory API ──→ 提取并存储对话事实

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

步骤一：开通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。

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。

配置参数说明：

步骤四：启动或重启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（存储记忆）：发送请记住：我的服务器IP是192.168.1.100，部署目录是/opt/app

• memory_get（获取记忆详情）：发送帮我获取记忆 <memory_id> 的详细内容

工作原理

自动召回流程

当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通信：

{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