# EverOS OpenClaw Plugin

通过自然语言对话为 **OpenClaw / 龙虾** 提供持久记忆能力。

这个插件保留当前 OpenClaw 的 `context-engine` 架构，并连接到自托管的 EverOS backend。其后端能力由 [EverOS](https://github.com/EverMind-AI/EverOS) 提供。

## 它能做什么

- 在每次回复前通过 `assemble()` 自动回忆相关记忆
- 在每轮对话后通过 `afterTurn()` 自动保存新内容
- 用户只需要正常聊天
- 不需要手动调用 `memory_store` 或 `memory_search`

重要说明：

- 这是一个 `context-engine` 插件
- 它不是 `memory` slot 插件
- 为避免冲突，安装时会把 `plugins.slots.memory` 设置为 `none`

## 快速开始

推荐安装方式：

```bash
npx --yes --package @evermind-ai/openclaw-plugin everos-install
```

安装器会：

- 复用已有的 `~/.openclaw/openclaw.json`
- 把插件路径写入 `plugins.load.paths`
- 把 `evermind-ai-everos` 写入 `plugins.allow`
- 设置 `plugins.slots.contextEngine = "evermind-ai-everos"`
- 设置 `plugins.slots.memory = "none"`
- 为插件创建或补齐默认配置

安装完成后：

```bash
openclaw gateway restart
```

然后用自然语言验证：

```text
记住：我喜欢意式浓缩。
我喜欢什么咖啡？
```

## 后端

默认后端地址：

```text
http://localhost:1995
```

健康检查：

```bash
curl http://localhost:1995/health
```

如果你还没有启动 EverOS backend：

```bash
git clone https://github.com/EverMind-AI/EverOS.git
cd EverOS
docker compose up -d
curl -LsSf https://astral.sh/uv/install.sh | sh
uv sync
cp env.template .env
# 编辑 .env
uv run python src/run.py
```

## 自然语言记忆是如何工作的

运行时流程：

1. 用户发送一条普通消息。
2. `assemble()` 去 EverOS backend 搜索相关记忆。
3. 命中的记忆被注入为上下文。
4. OpenClaw 正常回复。
5. `afterTurn()` 把这一轮的新内容写回 EverOS backend。

所以用户看到的体验是：

- “记住：我偏好深色模式”
- 之后再问：“我偏好什么 UI 风格？”

整个过程不需要显式调用记忆工具。

## OpenClaw 配置示例

期望的配置结构如下：

```json
{
  "plugins": {
    "allow": ["evermind-ai-everos"],
    "slots": {
      "memory": "none",
      "contextEngine": "evermind-ai-everos"
    },
    "entries": {
      "evermind-ai-everos": {
        "enabled": true,
        "config": {
          "baseUrl": "http://localhost:1995",
          "userId": "everos-user",
          "groupId": "everos-group",
          "topK": 5,
          "memoryTypes": ["episodic_memory"],
          "retrieveMethod": "hybrid",
          "apiVersion": "auto",
          "agentMode": false
        }
      }
    }
  }
}
```

## 配置项


| 字段               | 默认值                     | 说明                                                                          |
| ---------------- | ----------------------- | --------------------------------------------------------------------------- |
| `baseUrl`        | `http://localhost:1995` | EverOS backend 地址                                                           |
| `userId`         | `everos-user`           | 记忆归属的用户标识                                                                   |
| `groupId`        | `everos-group`          | 共享记忆命名空间                                                                    |
| `topK`           | `5`                     | 最多检索条目数                                                                     |
| `memoryTypes`    | `["episodic_memory"]`   | 要搜索的记忆类型；开启 `agentMode` 时会自动加入 `agent_memory`                                |
| `retrieveMethod` | `hybrid`                | 检索模式（`keyword` / `vector` / `hybrid` / `agentic`；`rrf` 已弃用）                  |
| `apiVersion`     | `auto`                  | 后端 API 版本；`auto` 会在启动时探测一次，`v1` / `legacy` 强制锁定                              |
| `agentMode`      | `false`                 | 是否捕获完整的工具调用轨迹 — 见下方 [Agent Memory 章节](#agent-memory)                        |

## Agent Memory

当后端是 V1 EverMemOS（自动探测）时，把 `agentMode` 设成 `true` 可以开启更丰富的记忆链路 —— 不只存 user / assistant 文本，而是捕获 agent 的**完整工具调用轨迹**：

```json
"config": {
  ...
  "agentMode": true
}
```

### 开启后会发生什么

- **写路径**从 `POST /api/v1/memories`（仅文本）切到 `POST /api/v1/memories/agent` —— 整轮包括 assistant 的 `tool_calls` 和按 `tool_call_id` 串联起来的 tool result 都会发给后端。
- **检索路径**自动把 `agent_memory` 加进搜索请求，会同时召回：
  - **`agent_case`** —— 具体的过往轨迹（任务意图、agent 实际采用的方法、关键决策洞察、质量分）
  - **`agent_skill`** —— 由多个 case 聚类抽出的**可复用模式**（名字、描述、模式正文、置信度、成熟度）
- **Prompt 注入**在原本的 `<episodic>` 前面增加 `<skills>` 和 `<cases>` 块 —— 高置信度的可复用模式优先注入。

### 为什么值得 opt in

实测一个工具密集任务（4 天京都旅行规划，调用 web_search + doc_create + 飞书 API 自定义脚本）：

- 第一次跑：agent 用了 18 条消息的工具链（搜索、构造 blocks JSON、写 Python 脚本调用飞书 API 追加内容）才完成任务。
- 一次类似的后续问题（"再做一个 7 天的札幌旅行规划"）：上一轮抽出的 skill `Multi-Part Travel Planning with Document Automation` 被注入 prompt，agent **直接复用模式**，只用 2 条消息就给出答案，完全跳过了探索性的工具调用。

需要知道的成本：

| 成本     | 说明                                                                                  |
| ------ | ----------------------------------------------------------------------------------- |
| 每轮写入更大 | 轨迹 POST 是纯文本的 5-10 倍                                                                |
| 后端 LLM 成本 | 每条 trajectory 在后端会触发一次 `agent_case` 抽取的 LLM 调用（约 7 秒，后端异步执行）                       |
| 抽取延迟   | case 在对话边界（或 flush）触发时抽出；单轮短 DM 可能要等到累积够内容才会产出 case                                |
| 后端版本要求 | 必须 V1 EverMemOS；老后端上插件会一次性 warn 并自动降级到纯文本写入                                        |

如果你不开 agentMode，插件行为和 2.0 完全一致（纯文本写入，只有 episodic memory）。在 V1 后端上，插件会在启动时打一条一次性提示，温和地建议你启用：

```text
[evermind-ai-everos] tip: backend supports V1 agent memory.
Set "agentMode": true in the plugin config to enable agent_case / agent_skill retrieval.
```


## 手动安装

```bash
npm install -g @evermind-ai/openclaw-plugin
everos-install
```

## 故障排查


| 问题        | 解决方式                                                                  |
| --------- | --------------------------------------------------------------------- |
| 插件未加载     | 检查 `plugins.allow`、`plugins.load.paths`、`plugins.slots.contextEngine` |
| 后端连接失败    | 检查 `baseUrl`，并执行 `curl <baseUrl>/health`                              |
| 没有回忆出记忆   | 检查后端数据，并尝试更具体的问题                                                      |
| 没有保存记忆    | 检查 EverOS backend 写入接口是否正常                                            |
| 与其他记忆插件冲突 | 确认 `plugins.slots.memory = "none"`                                    |


## 相关文件

- `index.js`：插件入口（注册）
- `src/engine.js`：ContextEngine 生命周期实现
- `src/convert.js`：OpenClaw 消息转 EverOS 格式
- `src/api.js`：EverOS backend REST API 客户端
- `src/messages.js`：消息归一化与轮次收集
- `src/prompt.js`：记忆搜索结果解析与 prompt 构建
- `src/subagent-assembler.js`：记忆上下文组装
- `bin/install.js`：安装器与配置引导
- `openclaw.plugin.json`：插件元数据与配置结构

## 许可证

Apache-2.0