Tools
Memory Openviking
By OpenClaw plugin: long-term semantic memory via OpenViking
Install
npm install --ignore-scriptsConfiguration Example
{
"plugins": {
"allow": ["memory-openviking"],
"entries": {
"memory-openviking": {
"enabled": true,
"config": {
"serverPort": 19933,
"commitEveryN": 5,
"dataPath": "~/.openclaw/openviking-data",
"embedding": {
"provider": "openai",
"apiBase": "https://openrouter.ai/api/v1",
"apiKey": "<YOUR_OPENROUTER_API_KEY>",
"model": "openai/text-embedding-3-small",
"dimension": 1536
},
"vlm": {
"provider": "openrouter",
"apiBase": "https://openrouter.ai/api/v1",
"apiKey": "<YOUR_OPENROUTER_API_KEY>",
"model": "google/gemini-3-flash-preview"
}
}
}
}
}
}README
# openclaw-memory-openviking
OpenClaw 插件：基于 [OpenViking](https://github.com/volcengine/OpenViking) 的长期语义记忆后端。
## 为什么需要这个插件
OpenClaw 原生记忆系统基于文件（`MEMORY.md`）和 SQLite，存在根本性局限：全量加载撑爆 context window、无语义检索、无自动提取、无去重合并。
本插件用 OpenViking 替代文件记忆，实现：
- **语义检索**：向量相似度 top-k 检索，替代全文加载，token 消耗恒定
- **自动提取**：VLM 自动分析对话，提取 6 类长期记忆（profile/preferences/entities/events/cases/patterns）
- **自动去重**：新信息 create / 补充 merge / 重复 skip / 过时 delete
- **噪声过滤**：VLM 判断记忆价值，闲聊不提取
- **零侵入**：通过 Plugin hook 机制扩展，OpenClaw 核心代码不做任何修改
## 工作原理
```
用户消息 → OpenClaw Gateway
↓
before_agent_start hook → 语义检索相关记忆（~1s）→ 注入 LLM 上下文
↓
LLM 收到精准的记忆片段 → 生成回答
↓
agent_end hook → 自动写入 OpenViking session（~0.03s）
↓
每 5 轮自动 commit → VLM 分析 → 提取长期记忆 → 向量化索引
↓
/new 或 /reset → before_reset hook → 强制 commit 未提交的记忆
```
## 功能
- **自动记忆召回**：每次生成回复前自动检索相关历史记忆（`before_agent_start` hook）
- **自动记忆写入**：每次回复后自动捕获对话内容（`agent_end` hook）
- **自动记忆提取**：每 N 轮自动 commit，由 VLM 分析并提取长期记忆
- **会话切换保护**：`/new` 或 `/reset` 时自动补偿 commit，最多等待 8 秒
- **指令跳过**：所有 `/` 开头的命令不触发 recall，避免无意义检索
- **并行检索**：同时搜索 `user/memories` 和 `agent/memories`，3 秒超时
- **server 生命周期管理**：插件自动启动/停止 OpenViking HTTP server
- **配置集成**：所有配置集中在 `openclaw.json`，插件启动时自动生成 `~/.openviking/ov.conf`
## 前置依赖
### 1. 安装 Python 3.11 + Go 编译器
**macOS**
```bash
brew install [email protected] go
```
**Ubuntu / Debian**
```bash
sudo apt update
sudo apt install -y software-properties-common build-essential cmake
sudo add-apt-repository -y ppa:deadsnakes/ppa
sudo apt install -y python3.11 python3.11-venv python3.11-dev
wget https://go.dev/dl/go1.23.6.linux-amd64.tar.gz
sudo rm -rf /usr/local/go && sudo tar -C /usr/local -xzf go1.23.6.linux-amd64.tar.gz
echo 'export PATH=$PATH:/usr/local/go/bin' >> ~/.bashrc && source ~/.bashrc
```
**CentOS / RHEL / AlmaLinux**
```bash
sudo yum install -y python3.11 python3.11-devel
sudo yum groupinstall -y "Development Tools" && sudo yum install -y cmake
wget https://go.dev/dl/go1.23.6.linux-amd64.tar.gz
sudo rm -rf /usr/local/go && sudo tar -C /usr/local -xzf go1.23.6.linux-amd64.tar.gz
echo 'export PATH=$PATH:/usr/local/go/bin' >> ~/.bashrc && source ~/.bashrc
```
> ARM64 服务器（如 AWS Graviton）Go 下载链接改为 `go1.23.6.linux-arm64.tar.gz`。
验证：
```bash
python3.11 --version # 期望 3.11.x
go version # 期望 go1.x
```
### 2. 安装 OpenViking SDK
```bash
git clone https://github.com/volcengine/OpenViking.git /tmp/openviking-src
python3.11 -m venv ~/.openclaw/openviking-venv
~/.openclaw/openviking-venv/bin/pip install --upgrade pip
# 如果通过 socks 代理访问外网（直连的跳过）
~/.openclaw/openviking-venv/bin/pip install "httpx[socks]"
# 从源码编译安装（国内服务器加 GOPROXY=https://goproxy.cn,direct）
~/.openclaw/openviking-venv/bin/pip install /tmp/openviking-src
```
验证：
```bash
~/.openclaw/openviking-venv/bin/python -c "from openviking import SyncOpenViking; print('OK')"
```
> 编译耗时约 2-5 分钟。如果报 `No module named 'openviking.storage.vectordb.engine'`，检查 Go 和网络。
## 安装插件
### 从本地路径安装
```bash
openclaw plugins install /path/to/openclaw-memory-openviking
```
### 从 npm 安装
```bash
openclaw plugins install openclaw-memory-openviking
```
### 从 GitHub 安装
```bash
git clone https://github.com/openclaw/memory-openviking.git /tmp/openclaw-memory-openviking
openclaw plugins install /tmp/openclaw-memory-openviking
```
> 安装时会提示 `dangerous code patterns: child_process`，这是因为插件需要启动 OpenViking Python server 进程，属于正常行为。
## 配置
在 `~/.openclaw/openclaw.json` 的 `plugins` 中添加：
```json
{
"plugins": {
"allow": ["memory-openviking"],
"entries": {
"memory-openviking": {
"enabled": true,
"config": {
"serverPort": 19933,
"commitEveryN": 5,
"dataPath": "~/.openclaw/openviking-data",
"embedding": {
"provider": "openai",
"apiBase": "https://openrouter.ai/api/v1",
"apiKey": "<YOUR_OPENROUTER_API_KEY>",
"model": "openai/text-embedding-3-small",
"dimension": 1536
},
"vlm": {
"provider": "openrouter",
"apiBase": "https://openrouter.ai/api/v1",
"apiKey": "<YOUR_OPENROUTER_API_KEY>",
"model": "google/gemini-3-flash-preview"
}
}
}
}
}
}
```
重启 gateway 生效：
```bash
openclaw gateway restart
```
### 配置字段说明
| 字段 | 说明 | 默认值 |
|------|------|--------|
| `serverPort` | OpenViking HTTP server 端口 | `19933` |
| `commitEveryN` | 每 N 轮自动 commit | `5` |
| `dataPath` | OpenViking 数据存储路径 | `~/.openclaw/openviking-data` |
| `embedding.provider` | Embedding provider | `openai` |
| `embedding.apiBase` | Embedding API 地址 | `https://openrouter.ai/api/v1` |
| `embedding.apiKey` | Embedding API key | - |
| `embedding.model` | Embedding 模型 | `openai/text-embedding-3-small` |
| `embedding.dimension` | Embedding 维度 | `1536` |
| `vlm.provider` | VLM provider | `openrouter` |
| `vlm.apiBase` | VLM API 地址 | `https://openrouter.ai/api/v1` |
| `vlm.apiKey` | VLM API key | - |
| `vlm.model` | VLM 模型 | `google/gemini-3-flash-preview` |
## 配置 AGENTS.md
将 `~/.openclaw/workspace/AGENTS.md` 中的 Memory 部分替换为：
```markdown
## Memory
OpenViking is your continuity. It runs as a plugin inside the Gateway process.
- **Read**: Automatically injected into your context before every reply (via `before_agent_start` hook). You will see a "Recalled Memories" section if relevant memories exist.
- **Write**: Automatically captured after every reply (via `agent_end` hook). Every 5 turns, OpenViking auto-commits and extracts long-term memories.
- **You don't need to call any tool or skill for memory** — it's fully automatic.
- **Fallback**: If OpenViking is unavailable, conversations continue normally.
- Do NOT read or write `MEMORY.md` or `memory/*.md` — they are archived.
```
## 更新插件
修改源码后，重新安装并重启 gateway：
```bash
# 删除旧版本
rm -rf ~/.openclaw/extensions/memory-openviking
# 重新安装
openclaw plugins install /path/to/openclaw-memory-openviking
# 重启 gateway
openclaw gateway restart
```
或手动同步（跳过 `openclaw plugins install` 的交互流程）：
```bash
# 删除旧版本
chmod -R u+rwx ~/.openclaw/extensions/memory-openviking
rm -rf ~/.openclaw/extensions/memory-openviking
# 拷贝新版本（排除不必要的文件）
rsync -a --exclude node_modules --exclude .git --exclude coverage \
/path/to/openclaw-memory-openviking/ ~/.openclaw/extensions/memory-openviking/
# 安装运行时依赖
cd ~/.openclaw/extensions/memory-openviking && pnpm install --ignore-scripts --prod
# 重启 gateway
openclaw gateway restart
```
## 验证
```bash
# 检查插件状态
openclaw plugins list | grep memory-openviking
# 检查 OpenViking server 健康状态
curl -s http://127.0.0.1:19933/health
# 期望：{"status":"ok"}
# 检查 gateway 日志
grep "[ov-memory]" ~/.openclaw/logs/gateway.log | tail -5
# 期望：[ov-memory] OpenViking server ready
```
功能验证：
1. 对 OpenClaw 说："记一下我喜欢蓝色"
2. 发 `/new` 开新会话
3. 问："我喜欢什么颜色？"
4. 期望：能回答出"蓝色"
## 性能
| 操作 | 延迟 | 说明 |
|------|------|------|
| recall（记忆检索） | ~1.0s | Embedding API 网络调用（并行 + 3s 超时） |
| ingest（记忆写入） | ~0.03s | HTTP 本地调用 |
| commit（记忆提取） | ~3-5s | VLM 分析 + Embedding 向量化，每 N 轮触发一次 |
### Token 消耗
| 操作 | 频率 | API 调用 | 大约消耗 |
|------|------|----------|----------|
| recall（检索） | 每轮 | Embedding 1 次 | ~100 tokens |
| write（写入） | 每轮 | 无（HTTP 本地） | 0 |
| commit（提取+去重） | 每 5 轮 | VLM 1-2 次 + Embedding 数次 | ~3000-5000 tokens |
按 gemini-3-flash（$0.1/M input），一次 commit 约 $0.0004。
## 日志
- Gateway 日志：`~/.openclaw/logs/gateway.log`（搜索 `[ov-memory]`）
- OpenViking server 日志：`~/.openclaw/logs/openviking-server.log`
## 项目结构
```
openclaw-memory-openviking/
├── index.ts # 插件入口 — 薄装配层，注册 hooks & service
├── openclaw.plugin.json # 插件清单（id, configSchema, uiHints）
├── src/
│ ├── api.ts # OpenViking HTTP 请求封装（含超时保护）
│ ├── config.ts # 配置生成 & ov.conf 文件写入
│ ├── memory.ts # recall / ingest / commit 核心逻辑
│ ├── server.ts # OpenViking server 生命周期管理
│ └── types.ts # 共享 TypeScript 接口
├── tests/ # Vitest 测试
├── package.json
├── tsconfig.json
├── vitest.config.ts
├── .oxlintrc.json # oxlint 配置
└── .oxfmtrc.jsonc # oxfmt 格式化配置
```
## 开发
```bash
pnpm install # 安装依赖
pnpm type-check # TypeScript 类型检查
pnpm lint # oxlint 代码质量检查
pnpm test # Vitest 测试
pnpm format # oxfmt 格式化
```
## License
MIT
tools
Comments
Sign in to leave a comment