Agent Harness

OpenClaw

Add long-term memory to OpenClaw agents using the Memaster plugin with skills-based memory extraction, recall and Dream consolidation.

@memaster/openclaw-memaster

给 OpenClaw 智能体接入 Memaster 后， Agent 可以在会话之间记住用户偏好、长期事实、项目规则和业务上下文。你不需要改 Agent 业务代码，只需安装插件并启用 memory backend。

Skills-based extraction用 Triage / Recall / Dream 三层 skills 自动抽取、召回和整理长期记忆。

Zero code changes通过 OpenClaw plugin slot 接入，不侵入既有 Agent 业务逻辑。

Cloud managed默认连接 api.memaster.cn，配额、API Key、请求日志都可在控制台管理。

概览

Memaster OpenClaw 插件分四层 skills：

Triage（分诊） —— 用结构化协议从对话里抽取"持久事实"，结合 importance gate（重要性闸门）和 domain overlay（领域配置）过滤噪声。
Recall（召回） —— 在 Agent 每一轮回复前，先按当前上下文检索相关记忆并注入 system prompt，支持重排（rerank）与关键词检索。
Dream（梦回） —— 周期性记忆整理：合并重复条目、解决冲突事实、清理已过期的旧记忆。
Agent Tools —— 8 个显式记忆工具，让 Agent 在对话中按需调用 memory_add / memory_search 等动作。

启用 autoCapture 后写入完全无感，启用 autoRecall 后召回也完全无感。一条命令即可初始化：

openclaw memaster init

环境要求

OpenClaw >= 2026.4.25
一个 Memaster 云端账号或企业版私有化实例
Node.js 20+（OpenClaw 自带运行时）

openclaw --version
# OpenClaw 2026.4.25 (aa36ee6) 或更高

安装

最快路径：直接对你的 OpenClaw Agent 发一条 setup 指令，它会自动跳到设置向导。

Setup Memaster from memaster.cn/claw-setup

也可以参照下文的 Manual Config（手动配置） 模式。

设置与配置

理解 `userId`

Memaster 用 userId 区分不同终端用户的记忆，强烈建议复用你应用内已有的用户标识，例如：

应用内部 ID，如 "user_123"、"alice@example.com"
UUID，如 "550e8400-e29b-41d4-a716-446655440000"
简单用户名，如 "alice"

⚠️

userId 一旦写入便会成为该用户所有记忆的归属键。请保持稳定——切换 userId 等于切换记忆库，旧记忆不会再被检索到。

平台模式（Memaster 云）

@memaster/openclaw-memaster 默认使用 Memaster 云服务 (opens in a new tab) 作为后端，免运维、自动扩容、配额可视化。

两种接入方式：

Chat Setup（推荐） —— 在任意 OpenClaw 聊天会话里运行 setup 命令，无需手动编辑配置或处理 API Key。
Manual Config（手动） —— 直接编辑 openclaw.json。

方式 1：Chat Setup（推荐）

在 OpenClaw 聊天里输入

Setup Memaster from memaster.cn/claw-setup

输入邮箱

OpenClaw 会引导你打开 Memaster 设置中心，输入注册邮箱。

粘贴 OTP

收到验证码后粘贴回聊天，向导会自动写入 apiKey、userId、skills 配置到 openclaw.json。

整个过程 30 秒以内，无需手工接触 API Key。

方式 2：Manual Config

通过 OpenClaw CLI 安装插件

openclaw plugins install @memaster/openclaw-memaster

获取 API Key

在 `openclaw.json` 中启用插件作为记忆后端

openclaw.json

{
  "plugins": {
    "slots": {
      "memory": "openclaw-memaster"
    },
    "entries": {
      "openclaw-memaster": {
        "enabled": true,
        "config": {
          "apiKey": "${MEMASTER_API_KEY}",
          "baseUrl": "https://api.memaster.cn",
          "userId": "alice",
          "skills": {
            "triage": { "enabled": true },
            "recall": {
              "enabled": true,
              "tokenBudget": 1500,
              "rerank": true,
              "keywordSearch": true,
              "identityAlwaysInclude": true
            },
            "dream": { "enabled": true },
            "domain": "companion"
          }
        }
      }
    }
  }
}

私有化模式（Self-hosted）

企业版用户可以将 baseUrl 指向私有化部署的 Memaster 实例：

openclaw.json

{
  "plugins": {
    "entries": {
      "openclaw-memaster": {
        "config": {
          "apiKey": "${MEMASTER_API_KEY}",
          "baseUrl": "https://memaster.your-company.com",
          "userId": "alice"
        }
      }
    }
  }
}

需要私有化？联系 sales@memaster.cn。

短期 vs 长期记忆

Session（短期） —— autoCapture 写入的记忆默认绑定 runId，作用范围仅在当前会话。会话结束后这些记忆不会自动召回到下一个会话。
User（长期） —— Agent 通过 memory_add 工具显式写入，默认 longTerm: true，跨所有会话持久存在该用户名下。

runId   ─▶ session-scoped memories
userId  ─▶ long-term memories（默认）

Agent Tools

启用插件后，OpenClaw Agent 会自动注册以下 8 个记忆工具：

工具名	用途
`memory_search`	按 `query` 检索，支持 `scope` / `categories` / `filters` 过滤
`memory_add`	写入新记忆，支持 `text` / `facts` / `category` / `importance` / `metadata`
`memory_get`	按 `memoryId` 取单条
`memory_list`	列出该 `userId` / `agentId` 下记忆，支持 `scope`
`memory_update`	修改已有记忆
`memory_delete`	删除单条或批量删除（`all: true` + `query`）
`memory_event_list`	列出后台抽取/整理事件
`memory_event_status`	查看某次后台事件的状态（pending / done / failed）

memory_search 与 memory_list 的 scope 字段可选 "session"、"long-term"、"all"。

CLI 命令

所有命令都支持 --json 输出，便于脚本化。

# 检索全部记忆（长期 + 会话）
openclaw memaster search "用户会几种语言"
 
# 仅检索长期记忆
openclaw memaster search "用户会几种语言" --scope long-term
 
# 仅检索当前会话短期记忆
openclaw memaster search "用户会几种语言" --scope session
 
# 列出全部记忆
openclaw memaster list
openclaw memaster list --user-id alice --top-k 20
 
# JSON 输出
openclaw memaster search "preferences" --json
openclaw memaster stats --json
 
# 帮助
openclaw memaster help --json

配置选项

通用选项

选项	类型	说明
`apiKey`	`string`	Memaster API Key（推荐用 `${MEMASTER_API_KEY}` 注入）
`baseUrl`	`string`	API 地址，默认 `https://api.memaster.cn`
`userId`	`string`	终端用户标识，必填
`agentId`	`string?`	Agent 标识，可选，便于多 Agent 隔离

Skills 选项

{
  "skills": {
    "triage":  { "enabled": true },
    "recall":  {
      "enabled": true,
      "tokenBudget": 1500,           // 召回内容注入 prompt 的 token 上限
      "rerank": true,                // 启用 LLM rerank
      "keywordSearch": true,         // 同时执行关键词检索
      "identityAlwaysInclude": true  // identity 类记忆永远参与召回
    },
    "dream":   { "enabled": true },
    "domain":  "companion"           // 领域 overlay：companion / coach / coding / customer-support
  }
}

autoCapture / autoRecall

{
  "autoCapture": true,    // 每轮对话结束后自动 triage 写入
  "autoRecall":  true     // 每轮 user 输入前自动 recall 注入
}

插件管理

升级插件

openclaw plugins update @memaster/openclaw-memaster

检查插件状态

openclaw plugins status @memaster-ai/openclaw-memaster
openclaw memaster stats --json

故障排查

`plugins.allow excludes memaster` 错误

OpenClaw 默认拒绝未授权插件。把插件加入 allow 列表：

openclaw.json

{
  "plugins": {
    "allow": ["@memaster/openclaw-memaster"]
  }
}

插件未激活

运行 openclaw plugins status 确认 enabled: true
确认 slots.memory 指向 openclaw-memaster
检查 MEMASTER_API_KEY 环境变量是否已注入
查看 ~/.openclaw/logs/plugin-memaster.log

插件升级未生效

openclaw plugins reinstall @memaster/openclaw-memaster

隐私与安全

数据流

OpenClaw Agent ──> Memaster 插件 ──> https://api.memaster.cn ──> 你的私有 namespace

所有记忆按 userId 严格隔离，不同 userId 之间不会交叉召回。

autoCapture / autoRecall

可在配置中关闭：

{
  "autoCapture": false,
  "autoRecall":  false
}

关闭后，记忆只在 Agent 显式调用 memory_add / memory_search 时才会读写。

凭证保护

API Key 仅存储在 ~/.openclaw/secrets/（macOS 启用 Keychain，Windows 启用 Credential Manager）
插件不会把 API Key 写入日志或 telemetry

Telemetry

插件默认不发送任何 telemetry。可通过 MEMASTER_TELEMETRY=1 显式启用聚合错误上报（无个人信息）。

System Prompt 上下文

autoRecall 注入到 system prompt 的内容会包含：召回记忆原文 + 召回 token 数 + 召回时间戳。不包含其他用户的记忆。

下一步

🦅 Hermes Agent 接入 🔧 REST API 参考 📖 核心概念

GitHub Copilot Hermes Agent

OpenClaw

概览

环境要求

安装

设置与配置

理解 userId

平台模式（Memaster 云）

方式 1：Chat Setup（推荐）

在 OpenClaw 聊天里输入

输入邮箱

粘贴 OTP

方式 2：Manual Config

通过 OpenClaw CLI 安装插件

获取 API Key

在 openclaw.json 中启用插件作为记忆后端

私有化模式（Self-hosted）

短期 vs 长期记忆

Agent Tools

CLI 命令

配置选项

通用选项

Skills 选项

autoCapture / autoRecall

插件管理

升级插件

检查插件状态

故障排查

plugins.allow excludes memaster 错误

插件未激活

插件升级未生效

隐私与安全

数据流

autoCapture / autoRecall

凭证保护

Telemetry

System Prompt 上下文

下一步

理解 `userId`

在 `openclaw.json` 中启用插件作为记忆后端

`plugins.allow excludes memaster` 错误