Agent Harness

Hermes Agent

Add long-term memory to Hermes agents using Memaster as a pluggable memory provider with automatic background sync and zero-latency prefetch.

memaster provider

Hermes 是 Nous Research 开源的对话式 Agent 框架，自带 MEMORY.md / USER.md 文件式短期记忆。Memaster Hermes 集成把云端长期记忆作为可插拔 Provider 附加进去——预取在后台、写入在后台，对会话延迟零影响。

Zero-latency recall在后台预取记忆并缓存，用户下一轮输入时直接命中上下文。

Background sync对话结束后异步提交到 Memaster，不阻塞 Hermes 当前推理流程。

Fault tolerant内置 circuit breaker，云端临时不可达时 Agent 仍可正常工作。

概览

集成的核心是「三阶段非阻塞循环」：

1. 在 Agent 回复之前（Prefetch）

每次 user 发言后，Hermes 立刻向 Memaster 发起 memaster_search（异步），把召回结果缓存为下一轮的"已就绪上下文"。不会阻塞 Agent 推理。

2. 在 Agent 回复之后（Sync）

每完成一轮 (user message, assistant response)，Hermes 在后台守护线程里把这一轮提交给 Memaster，由服务端自动抽取事实、去重、入库。不会阻塞下一轮。

3. 为下一轮做后台预取

紧接着上一步，Hermes 会基于最新对话再次 prefetch，准备好下一轮要用的记忆。用户感知的延迟 = 0（命中缓存）。

user input ─┬──▶ [prefetch from cache, 0ms] ─▶ Agent thinks ─▶ assistant reply
            │                                                       │
            │                                       ┌───────────────┘
            │                                       ▼
            └────────────[ background sync to Memaster ]
                         [ background prefetch for next turn ]

Agent Tools

集成会向 Hermes 注册 3 个核心工具：

工具名	用途
`memaster_profile`	取当前用户画像摘要（identity 类记忆 + 长期偏好聚合）
`memaster_search`	主动检索，支持 `rerank`、`top_k`、`filters`
`memaster_conclude`	显式写入一条结论性记忆，可设 `infer=False` 跳过自动抽取直接落库

安装

curl -fsSL https://raw.githubusercontent.com/memaster-ai/hermes-memaster/main/scripts/install.sh | bash
source ~/.bashrc

安装脚本会：

安装 memaster Python SDK（pip）
把 Memaster Provider 注册到 ~/.hermes/providers/memaster.py
在 ~/.hermes/.env 中预置 MEMASTER_API_KEY 占位

也可以手动安装：pip install memaster 然后参照 Manual Configuration。

设置

方式 1：交互式 Setup Wizard（推荐）

hermes memory setup

向导会引导你：

打开 memaster.cn/dashboard 创建 API Key
粘贴 msk_xxx
写入 ~/.hermes/memaster.json
启用 memory.provider = memaster

方式 2：手动配置

hermes config set memory.provider memaster
echo "MEMASTER_API_KEY=msk_xxx" >> ~/.hermes/.env

或直接编辑 ~/.hermes/config.yaml：

~/.hermes/config.yaml

memory:
  provider: memaster

配置选项

~/.hermes/memaster.json 支持以下字段：

字段	环境变量	默认值	说明
`api_key`	`MEMASTER_API_KEY`	—	Memaster API Key（必填）
`base_url`	`MEMASTER_BASE_URL`	`https://api.memaster.cn`	API 地址，私有化部署时改成你自己的实例
`user_id`	`MEMASTER_USER_ID`	`hermes-user`	终端用户标识
`agent_id`	`MEMASTER_AGENT_ID`	`hermes`	Agent 标识
`rerank`	—	`true`	是否启用 LLM rerank
`top_k`	—	`5`	默认召回条数

~/.hermes/memaster.json

{
  "api_key": "${MEMASTER_API_KEY}",
  "base_url": "https://api.memaster.cn",
  "user_id": "alice",
  "agent_id": "hermes",
  "rerank": true,
  "top_k": 5
}

可用性保障（Reliability）

Memaster Hermes Provider 内置三层容错：

Circuit Breaker（熔断） —— 如果 Memaster API 连续失败 5 次，Provider 会停止调用 2 分钟后自动重试。期间 Agent 继续正常工作（无长期记忆）。
Non-blocking（非阻塞） —— 所有 API 调用都在后台守护线程中执行。慢请求或失败请求不会阻塞 Agent 当前会话。
Thread-safe（线程安全） —— Provider 内部使用 lazy initialization + lock，安全支持并发访问。

关键特性

零延迟召回 —— 记忆在后台预取并缓存，Agent 还没开始推理召回结果就已就位
服务端抽取 —— Memaster 在云端自动抽取事实、去重、合并，无需在客户端跑 LLM
非阻塞 —— 所有 API 调用全部进后台守护线程
容错 —— circuit breaker 保证 Memaster 临时不可达时 Agent 仍可工作
加性记忆 —— 与 Hermes 自带 MEMORY.md / USER.md 共存，不取代仅增强

与 Memaster Cloud 集成

Hermes 集成默认指向 Memaster 云端 (opens in a new tab)。你可以在 memaster.cn/dashboard 控制台中：

我的记忆 —— 实时查看 Hermes 写入的内容
记忆看板 —— 查看 Hermes 调用产生的请求量与配额消耗
API Keys —— 撤销 / 轮换 Hermes 使用的密钥

私有化用户把 base_url 指向自己的实例即可，所有功能保持一致。

下一步

🐳 OpenClaw 接入 🔧 REST API 参考 🐍 Python SDK

OpenClaw Dashboard