mirror of
https://github.com/TencentCloud/TencentDB-Agent-Memory
synced 2026-07-10 20:34:30 +00:00
chrishuan
224 lines
9.8 KiB
Markdown
224 lines
9.8 KiB
Markdown
# OpenClaw 适配参考：TencentDB Agent Memory
|
||
|
||
简体中文 · [English](./README.md)
|
||
|
||
该目录是一个 Agent 框架接入 TencentDB Agent Memory v2 API 的参考实现。它是 OpenClaw 的客户端插件：插件本身不做抽取、索引、场景归纳或画像生成，而是连接一个已经运行的 Memory Gateway，通过 TypeScript SDK 完成对话捕获、记忆召回和工具暴露。
|
||
|
||
在 standalone 本地模式下，推荐的 Memory Gateway 地址是 `http://127.0.0.1:8420`。默认约定是 `apiKey = "local"`、`serviceId = "default"`。如果 Gateway 显式启用了 `TDAI_GATEWAY_API_KEY`，则 `server.apiKey` 应使用同一个值。
|
||
|
||
## 架构
|
||
|
||
```text
|
||
OpenClaw runtime
|
||
└─ memory-tencentdb-client plugin
|
||
├─ hooks/capture.ts agent_end -> addConversation (L0)
|
||
├─ hooks/recall.ts before_prompt_build -> search + prompt 注入
|
||
├─ tools/memory-search.ts tdai_memory_search -> searchAtomic (L1)
|
||
├─ tools/conversation-search.ts tdai_conversation_search -> searchConversation (L0)
|
||
└─ tools/read-cos.ts tdai_read_cos -> 读取 L2/L3 文件
|
||
│
|
||
▼
|
||
@tencentdb-agent-memory/memory-sdk-ts
|
||
│ HTTP v2 API
|
||
▼
|
||
TencentDB Agent Memory Gateway（standalone :8420 或远端服务）
|
||
```
|
||
|
||
## 快速开始
|
||
|
||
推荐从仓库根目录执行自动安装脚本：
|
||
|
||
```bash
|
||
bash scripts/install-openclaw-plugin-v2.sh
|
||
```
|
||
|
||
脚本会检查/安装 OpenClaw CLI，安装插件依赖，构建插件，并通过 `openclaw plugins install -l` 将当前 `openclaw-plugin` 目录安装到 OpenClaw。默认还会更新 `~/.openclaw/openclaw.json`：设置 `plugins.slots.memory = "memory-tencentdb-client"`，启用插件，写入 standalone 默认的 `server`、`recall`、`capture` 配置。脚本会自动探测 OpenClaw 版本：**2026.4.24+** 会同时写入 `hooks.allowPromptInjection` / `hooks.allowConversationAccess`（non-bundled 插件需要 `allowConversationAccess=true` 才能采集对话）；**更老的版本会自动跳过**这两个字段——因为 2026.4.24 之前的 gateway 使用 strict zod schema，遇到这两个字段会启动失败。
|
||
|
||
可通过环境变量覆盖默认值：`OPENCLAW_CONFIG_FILE`、`TDAI_MEMORY_ENDPOINT`、`TDAI_MEMORY_API_KEY`、`TDAI_MEMORY_INSTANCE_ID`、`TDAI_MEMORY_RECALL_MAX_RESULTS`、`TDAI_MEMORY_CAPTURE_ENABLED`。如果只想安装插件、不修改 OpenClaw 配置，可设置 `WRITE_OPENCLAW_CONFIG=0`。
|
||
|
||
如需手动安装，可按下面步骤执行。
|
||
|
||
### 1. 安装 OpenClaw
|
||
|
||
如果你还没有安装 OpenClaw，请先安装 OpenClaw CLI：
|
||
|
||
```bash
|
||
curl -fsSL https://get.openclaw.dev | bash
|
||
```
|
||
|
||
确认命令可用：
|
||
|
||
```bash
|
||
openclaw --version
|
||
```
|
||
|
||
### 2. 安装依赖
|
||
|
||
```bash
|
||
cd openclaw-plugin
|
||
npm install
|
||
```
|
||
|
||
插件依赖 `@tencentdb-agent-memory/memory-sdk-ts`，也就是 v2 API 的 TypeScript SDK。
|
||
|
||
### 3. 构建
|
||
|
||
```bash
|
||
npm run build
|
||
```
|
||
|
||
### 4. 安装插件到 OpenClaw
|
||
|
||
开发或本地源码调试时，推荐以软链方式安装当前目录：
|
||
|
||
```bash
|
||
openclaw plugins install -l .
|
||
```
|
||
|
||
### 5. 配置插件
|
||
|
||
如果使用 `agentmemory/openclaw-memory` 容器镜像，镜像启动脚本已经自动完成下面这段配置，通常不需要手动修改。
|
||
|
||
如果使用 `scripts/install-openclaw-plugin-v2.sh`，脚本默认也会自动写入这段配置，并会自动按 OpenClaw 版本对 `hooks.*` 字段做版本门控。只有在 `WRITE_OPENCLAW_CONFIG=0` 或手动安装插件时，才需要自己编辑 OpenClaw 配置文件。
|
||
|
||
> ⚠️ **重要 —— `hooks.*` 与 OpenClaw 版本强相关。**
|
||
> `hooks.allowPromptInjection` / `hooks.allowConversationAccess` 是 **OpenClaw `2026.4.24`** 起才被 gateway schema 接受的字段。更老的版本（含 `2026.4.23`）使用 strict zod schema，**包含这两个字段会让 gateway 启动失败**。请按你本机 `openclaw --version` 显示的版本，**选择对应的示例**复制：
|
||
|
||
**示例 A —— OpenClaw `>= 2026.4.24`（推荐）：**
|
||
|
||
```jsonc
|
||
{
|
||
"plugins": {
|
||
"slots": {
|
||
"memory": "memory-tencentdb-client"
|
||
},
|
||
"entries": {
|
||
"memory-tencentdb-client": {
|
||
"enabled": true,
|
||
// 2026.4.24+ 上，non-bundled 插件必须显式 hooks.*。
|
||
// 缺少 allowConversationAccess=true 会让 L0 capture 被静默拦截。
|
||
"hooks": {
|
||
"allowPromptInjection": true,
|
||
"allowConversationAccess": true
|
||
},
|
||
"config": {
|
||
"server": {
|
||
"url": "http://127.0.0.1:8420",
|
||
"apiKey": "local",
|
||
"instanceId": "default"
|
||
},
|
||
"recall": {
|
||
"maxResults": 5,
|
||
"includePersona": true,
|
||
"includeSceneNav": true
|
||
},
|
||
"capture": {
|
||
"enabled": true
|
||
}
|
||
}
|
||
}
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
**示例 B —— OpenClaw `< 2026.4.24`（如 `2026.4.23`）：完全省略 `hooks` 块。**
|
||
|
||
```jsonc
|
||
{
|
||
"plugins": {
|
||
"slots": {
|
||
"memory": "memory-tencentdb-client"
|
||
},
|
||
"entries": {
|
||
"memory-tencentdb-client": {
|
||
"enabled": true,
|
||
// ⚠️ 不要添加 "hooks" 块。2026.4.23 及更早的 strict schema 会拒绝
|
||
// allowPromptInjection / allowConversationAccess，gateway 启动失败。
|
||
// 如需使用这两个字段，请升级 OpenClaw。
|
||
"config": {
|
||
"server": {
|
||
"url": "http://127.0.0.1:8420",
|
||
"apiKey": "local",
|
||
"instanceId": "default"
|
||
},
|
||
"recall": {
|
||
"maxResults": 5,
|
||
"includePersona": true,
|
||
"includeSceneNav": true
|
||
},
|
||
"capture": {
|
||
"enabled": true
|
||
}
|
||
}
|
||
}
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
如果 Gateway 启用了 `TDAI_GATEWAY_API_KEY`，请将 `server.apiKey` 设置成同一个值。`server.instanceId` 会作为 `x-tdai-service-id` 发送；standalone 模式默认使用 `default`。
|
||
|
||
`hooks.allowPromptInjection` 允许 `before_prompt_build` 注入召回上下文；`hooks.allowConversationAccess` 允许 `agent_end` 读取原始对话并写入 L0。**版本兼容性：**
|
||
- **OpenClaw `>= 2026.4.24`** —— 这两个字段才被 gateway schema 识别。non-bundled 插件必须显式 `allowConversationAccess=true`，否则会话钩子在注册阶段被静默拦截、L0 capture 不会落库；`allowPromptInjection` 未设置时默认放行，我们仍写 `true` 以锁定意图。
|
||
- **OpenClaw `< 2026.4.24`**（含 4.23 及更早）—— gateway 使用 strict zod schema，**会拒绝**这两个字段。**配置中不要包含 `hooks.*` 块**，否则 gateway 启动失败。安装脚本会自动按版本探测、在老版本上跳过该块。
|
||
|
||
### 6. 在 OpenClaw 中启用
|
||
|
||
插件 ID 是 `memory-tencentdb-client`。容器镜像中已经将它接入 memory slot。如果手动安装，请确保 OpenClaw 能加载该插件，并在 memory slot 中选中它。修改配置后可重启 Gateway：
|
||
|
||
```bash
|
||
openclaw gateway restart
|
||
```
|
||
|
||
## 适配职责
|
||
|
||
| 模块 | 实现文件 | 说明 |
|
||
|---|---|---|
|
||
| 对话捕获 | `src/hooks/capture.ts` | 对话结束后调用 `addConversation()` 写入 L0 |
|
||
| 记忆召回 | `src/hooks/recall.ts` | 构建 prompt 前搜索记忆并注入简洁上下文 |
|
||
| L1 工具 | `src/tools/memory-search.ts` | 让 Agent 主动搜索结构化记忆 |
|
||
| L0 工具 | `src/tools/conversation-search.ts` | 让 Agent 主动搜索历史对话 |
|
||
| L2/L3 读取工具 | `src/tools/read-cos.ts` | 让 Agent 在需要时读取场景或画像文件 |
|
||
|
||
## 配置项
|
||
|
||
| 字段 | 默认值 | 说明 |
|
||
|---|---|---|
|
||
| `server.url` | `http://127.0.0.1:8420` | Memory Gateway 地址 |
|
||
| `server.apiKey` | `""` | SDK 发送的 Bearer token。standalone 默认可用 `local`。 |
|
||
| `server.instanceId` | `default` | Memory 空间 ID，通过 `x-tdai-service-id` 发送 |
|
||
| `recall.maxResults` | `5` | 每轮最多注入多少条 L1 记忆 |
|
||
| `recall.includePersona` | `true` | 是否注入 L3 core/profile 上下文 |
|
||
| `recall.includeSceneNav` | `true` | 是否注入 L2 场景导航 |
|
||
| `capture.enabled` | `true` | 是否自动捕获完整对话轮次 |
|
||
| `hooks.allowPromptInjection` | `true` | 允许插件在 prompt 构建阶段注入召回上下文。未设置时默认放行，我们显式写 `true` 是为了锁定意图。**仅在 OpenClaw `>= 2026.4.24` 时写入此字段**——更老的 gateway 会用 strict schema 拒绝它。 |
|
||
| `hooks.allowConversationAccess` | `true` | 允许插件在 `agent_end` / `llm_input` / `llm_output` 读取原始对话用于 L0 写入。**non-bundled 插件必须显式 `true`**——否则会话钩子会在注册阶段被静默拦截，L0 capture 不会落库。**仅在 OpenClaw `>= 2026.4.24` 时写入此字段**——更老的 gateway 会用 strict schema 拒绝它。 |
|
||
|
||
## 文件结构
|
||
|
||
```text
|
||
openclaw-plugin/
|
||
├── openclaw.plugin.json # 插件清单
|
||
├── package.json # 依赖与构建脚本
|
||
├── index.ts # OpenClaw 入口
|
||
├── src/hooks/capture.ts # L0 捕获 hook
|
||
├── src/hooks/recall.ts # 召回 hook
|
||
├── src/tools/ # Agent 可调用工具
|
||
└── src/format.ts # prompt 格式化辅助
|
||
```
|
||
|
||
## 作为其它 Agent 的适配模板
|
||
|
||
如果你要适配其它 Agent 框架，可以复用同样模式：
|
||
|
||
1. 在一轮用户/助手对话完成后调用 `addConversation()`。
|
||
2. 在下一轮 prompt 构建前调用 `searchAtomic()`、`readCore()`，必要时调用 `listScenarios()`。
|
||
3. 只向 Agent prompt 注入简洁、带标签的记忆上下文。
|
||
4. 暴露 L1 搜索、L0 对话搜索、L2 场景读取等主动工具。
|
||
5. Adapter 保持无状态；存储、异步 L1/L2/L3 处理都交给 Memory Gateway。
|
||
|
||
## 注意
|
||
|
||
该插件只是客户端 adapter，不应在插件内启动 Memory Gateway 子进程，也不应在本地实现记忆抽取逻辑。standalone Gateway 启动方式与 SDK 示例见根目录 README。
|