openviking-memory

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

OpenViking Memory Guide

OpenViking 记忆指南

How It Works

工作原理

Auto-Capture: At the end of a conversation, automatically extracts memories from user messages
- ```
semantic
```
  mode: captures all qualifying user text, relying on OpenViking's extraction pipeline to filter
- ```
keyword
```
  mode: only captures text matching trigger words (e.g. "remember", "preference", etc.)
Auto-Recall: Before a conversation starts, automatically searches for relevant memories and injects them into context

自动捕获：对话结束时，自动从用户消息中提取记忆
- ```
semantic
```
  模式：捕获所有符合条件的用户文本，依赖OpenViking的提取管道进行过滤
- ```
keyword
```
  模式：仅捕获匹配触发词的文本（例如"remember"、"preference"等）
自动调取：对话开始前，自动搜索相关记忆并将其注入上下文

Available Tools

可用工具

memory_recall — Search Memories

memory_recall — 搜索记忆

Searches long-term memories in OpenViking, returns relevant results.

Parameter	Required	Description
`query`	Yes	Search query text
`limit`	No	Maximum number of results (defaults to plugin config)
`scoreThreshold`	No	Minimum relevance score 0-1 (defaults to plugin config)
`targetUri`	No	Search scope URI (defaults to plugin config)

Example: User asks "What programming language did I say I like?"

在OpenViking中搜索长期记忆，返回相关结果。

参数	是否必填	描述
`query`	是	搜索查询文本
`limit`	否	最大结果数（默认值为插件配置）
`scoreThreshold`	否	最低相关度分数 0-1（默认值为插件配置）
`targetUri`	否	搜索范围URI（默认值为插件配置）

示例：用户询问"我之前说过喜欢什么编程语言？"

memory_store — Manual Store

memory_store — 手动存储

Writes text to an OpenViking session and runs memory extraction.

Parameter	Required	Description
`text`	Yes	Information text to store
`role`	No	Session role (default `user` )
`sessionId`	No	Existing OpenViking session ID

Example: User says "Remember my email is xxx@example.com"

将文本写入OpenViking会话并运行记忆提取。

参数	是否必填	描述
`text`	是	要存储的信息文本
`role`	否	会话角色（默认 `user` ）
`sessionId`	否	现有OpenViking会话ID

示例：用户说"记住我的邮箱是xxx@example.com"

memory_forget — Delete Memories

memory_forget — 删除记忆

Delete by exact URI, or search and delete.

Parameter	Required	Description
`uri`	No	Exact memory URI (direct delete)
`query`	No	Search query (find then delete)
`targetUri`	No	Search scope URI
`limit`	No	Search limit (default 5)
`scoreThreshold`	No	Minimum relevance score

Example: User says "Forget my phone number"

通过精确URI删除，或搜索后删除。

参数	是否必填	描述
`uri`	否	精确的记忆URI（直接删除）
`query`	否	搜索查询（查找后删除）
`targetUri`	否	搜索范围URI
`limit`	否	搜索限制（默认5）
`scoreThreshold`	否	最低相关度分数

示例：用户说"忘记我的电话号码"

Configuration

配置项

Field	Default	Description
`mode`	`remote`	`local` (start local server) or `remote` (connect to remote)
`baseUrl`	`http://127.0.0.1:1933`	OpenViking server URL (remote mode)
`apiKey`	—	OpenViking API Key (optional)
`agentId`	`openclaw-<hostname>`	Identifies this agent (auto-generated, persisted to `~/.openviking/.agent-id` )
`configPath`	`~/.openviking/ov.conf`	Config file path (local mode)
`port`	`1933`	Local server port (local mode)
`targetUri`	`viking://user/memories`	Default search scope
`autoCapture`	`true`	Automatically capture memories
`captureMode`	`semantic`	Capture mode: `semantic` / `keyword`
`captureMaxLength`	`24000`	Maximum text length per capture
`autoRecall`	`true`	Automatically recall and inject context
`recallLimit`	`6`	Maximum memories injected during auto-recall
`recallScoreThreshold`	`0.01`	Minimum relevance score for recall
`ingestReplyAssist`	`true`	Add reply guidance when detecting multi-party conversation text

字段	默认值	描述
`mode`	`remote`	`local` （启动本地服务器）或 `remote` （连接远程服务器）
`baseUrl`	`http://127.0.0.1:1933`	OpenViking服务器URL（远程模式）
`apiKey`	—	OpenViking API密钥（可选）
`agentId`	`openclaw-<hostname>`	标识此Agent（自动生成，持久化到 `~/.openviking/.agent-id` ）
`configPath`	`~/.openviking/ov.conf`	配置文件路径（本地模式）
`port`	`1933`	本地服务器端口（本地模式）
`targetUri`	`viking://user/memories`	默认搜索范围
`autoCapture`	`true`	自动捕获记忆
`captureMode`	`semantic`	捕获模式： `semantic` / `keyword`
`captureMaxLength`	`24000`	每次捕获的最大文本长度
`autoRecall`	`true`	自动调取并注入上下文
`recallLimit`	`6`	自动调取时注入的最大记忆数量
`recallScoreThreshold`	`0.01`	调取的最低相关度分数
`ingestReplyAssist`	`true`	检测到多方对话文本时添加回复指引

Daily Operations

日常操作

bash

undefined

bash

undefined

Start (local mode: source env first)

启动（本地模式：先加载环境变量）

source ~/.openclaw/openviking.env && openclaw gateway

Start (remote mode: no env needed)

启动（远程模式：无需环境变量）

openclaw gateway

Check status

检查状态

openclaw status

Disable memory

禁用记忆功能

openclaw config set plugins.slots.memory none

Enable memory

启用记忆功能

openclaw config set plugins.slots.memory memory-openviking


Restart the gateway after changing the slot.

openclaw config set plugins.slots.memory memory-openviking


修改插槽配置后需重启网关。

Multi-Instance Support

多实例支持

If you have multiple OpenClaw instances, use

--workdir

to target a specific one:

bash

undefined

如果您有多个OpenClaw实例，使用

--workdir

指定特定实例：

bash

undefined

Install script

安装脚本

curl -fsSL ... | bash -s -- --workdir ~/.openclaw-openclaw-second

Setup helper

配置助手

npx ./examples/openclaw-memory-plugin/setup-helper --workdir ~/.openclaw-openclaw-second

Manual config (prefix openclaw commands)

手动配置（在openclaw命令前添加前缀）

OPENCLAW_STATE_DIR=~/.openclaw-openclaw-second openclaw config set ...

undefined

OPENCLAW_STATE_DIR=~/.openclaw-openclaw-second openclaw config set ...

undefined

Troubleshooting

故障排查

Symptom	Cause	Fix
`extracted 0 memories`	Wrong API Key or model name	Check `api_key` and `model` in `ov.conf`
`port occupied`	Port used by another process	Change port: `openclaw config set plugins.entries.memory-openviking.config.port 1934`
Plugin not loaded	Env file not sourced or slot not configured	Check `openclaw status` output
Inaccurate recall	recallScoreThreshold too low	Increase threshold or adjust recallLimit

症状	原因	解决方法
`extracted 0 memories`	API密钥或模型名称错误	检查 `ov.conf` 中的 `api_key` 和 `model`
`port occupied`	端口被其他进程占用	修改端口： `openclaw config set plugins.entries.memory-openviking.config.port 1934`
插件未加载	未加载环境文件或插槽未配置	检查 `openclaw status` 的输出
调取结果不准确	recallScoreThreshold过低	提高阈值或调整recallLimit