Self-evolving Context Database for AI Agents. Unify Agent Memory, Knowledge RAG and Skills.
Python agent-contextagent-memoryagent-pluginsagentic-ragcontext-databasedsh-pluginknowledge-basememorymemory-managementself-evolvingvector-database
docs(openclaw): document explicit memory writes (#2323)
Mingjian Quee42dd127416b
diff --git a/examples/openclaw-plugin/README.md b/examples/openclaw-plugin/README.mdindex b4d5e3973..0546ee597 100644--- a/examples/openclaw-plugin/README.md+++ b/examples/openclaw-plugin/README.md@@ -23,8 +23,9 @@ The agent runs install → setup → restart → verify automatically. See [INST| Stage | What happens ||-------|-------------|-| **Every turn** (`afterTurn`) | Your messages are archived into an OpenViking session |-| **On `/compact`** (`compact`) | Archived messages are extracted into long-term memories |+| **Every turn** (`afterTurn`) | New messages are appended to an OpenViking session; commit/extraction is threshold-triggered |+| **Explicit remember** (`memory_store`) | Important long-term facts can be written and committed immediately |+| **On `/compact`** (`compact`) | Pending session messages are committed and extracted into long-term memories || **Before each reply** (`assemble`) | Relevant memories are auto-retrieved and injected into context |## Tools@@ -34,7 +35,7 @@ Once installed, the plugin provides these agent tools:| Tool | Purpose ||------|---------|| `memory_recall` | Explicit long-term memory search |-| `memory_store` | Persist important information immediately |+| `memory_store` | Persist explicit long-term facts immediately || `memory_forget` | Delete memories by URI or query || `ov_archive_search` | Search across archives by keyword || `ov_archive_expand` | Expand an archive back to raw messages |@@ -206,6 +207,18 @@ After that, the plugin checks `pending_tokens`. Once the session crosses `commit- the current turn is not blocked waiting for extraction- if `logFindRequests` is enabled, the logs include the task id and follow-up extraction detail+This automatic path is best-effort and commit-dependent. Short but important facts can stay only in the live session until a threshold commit, `/compact`, or an explicit store happens.++### Explicit long-term memory writes++When the user explicitly asks the agent to remember, save, or store an important long-term fact, preference, project, or decision, prefer `memory_store` over waiting for normal auto-capture. `memory_store` writes the text to an OpenViking session and calls `commit(wait=true)`, so it is the reliable integration-side path for facts that should be available as long-term memory as soon as possible.++Use it as a complement to auto-capture, not a replacement:++- auto-capture still preserves ordinary conversation flow and batches extraction for cost and latency+- `memory_store` is for explicit durable-memory intent such as "remember my main project is X" or "save this preference"+- if `memory_store` commits but extracts 0 memories, check the OpenViking server extraction/model configuration; the explicit path triggered extraction, but the extractor did not produce a memory+### What `compact()` does`compact()` is the stricter synchronous boundary:@@ -222,7 +235,7 @@ So `afterTurn()` is closer to "incremental append plus threshold-triggered asyncBeyond automatic behavior, the plugin exposes seven tools directly:- `memory_recall`: explicit long-term memory search-- `memory_store`: write text into an OpenViking session and trigger commit+- `memory_store`: write explicit long-term facts into an OpenViking session and trigger commit- `memory_forget`: delete by URI, or search first and remove a single strong match- `ov_archive_expand`: expand a concrete archive back into raw messages- `add_resource`: import a document, directory, URL, or Git repository as an OpenViking resource@@ -233,7 +246,7 @@ They serve different roles:- automatic recall covers the default case where the model does not know what to search yet- `memory_recall` gives the model an explicit follow-up search path-- `memory_store` is for immediately persisting clearly important information+- `memory_store` is for immediately persisting clearly important information when the user expresses durable-memory intent- `ov_archive_expand` is the "go back to archive detail" escape hatch when summaries are not enough- `add_resource` lets the agent save explicit document or repository import requests without asking the user to remember slash commands- `add_skill` imports skills into OpenViking, while `add_resource` imports resourcesdiff --git a/examples/openclaw-plugin/README_CN.md b/examples/openclaw-plugin/README_CN.mdindex 5e3067f13..8a33fd84e 100644--- a/examples/openclaw-plugin/README_CN.md+++ b/examples/openclaw-plugin/README_CN.md@@ -23,8 +23,9 @@ Agent 会自动完成安装 → 配置 → 重启 → 验证。详见 [INSTALL-A| 阶段 | 行为 ||------|------|-| **每轮对话后** (`afterTurn`) | 消息自动归档到 OpenViking session |-| **`/compact` 时** (`compact`) | 归档消息被抽取为长期记忆 |+| **每轮对话后** (`afterTurn`) | 新消息追加到 OpenViking session;commit/抽取由阈值触发 |+| **明确要求记住** (`memory_store`) | 重要长期事实可立即写入并提交 |+| **`/compact` 时** (`compact`) | 待提交 session 消息被 commit 并抽取为长期记忆 || **回复前** (`assemble`) | 自动检索相关记忆并注入上下文 |## 工具@@ -34,7 +35,7 @@ Agent 会自动完成安装 → 配置 → 重启 → 验证。详见 [INSTALL-A| 工具 | 用途 ||------|------|| `memory_recall` | 显式检索长期记忆 |-| `memory_store` | 立即持久化重要信息 |+| `memory_store` | 立即持久化明确的长期事实 || `memory_forget` | 按 URI 或查询删除记忆 || `ov_archive_search` | 按关键词搜索历史 archive || `ov_archive_expand` | 展开某个 archive 的原始消息 |@@ -206,6 +207,18 @@ preflight 阶段的 `assemble()` 并不是简单地把旧聊天记录塞回来- 当前 turn 不会因为等待抽取而阻塞- 如果打开 `logFindRequests`,日志里能看到 task id 和后续抽取结果+这条自动路径是 best-effort,并且依赖 commit。短但重要的事实可能会先停留在 live session 里,直到阈值 commit、`/compact` 或显式存储发生后,才进入长期记忆抽取流程。++### 显式长期记忆写入++当用户明确要求 agent “记住”“保存”“存一下”某个重要长期事实、偏好、项目或决定时,应优先使用 `memory_store`,而不是等待普通 auto-capture 自然触发。`memory_store` 会把文本写入 OpenViking session 并调用 `commit(wait=true)`,因此是集成侧让重要事实尽快进入长期记忆的可靠路径。++它是 auto-capture 的补充,不是替代:++- auto-capture 继续负责普通对话流,并通过批处理平衡成本和延迟+- `memory_store` 面向明确的长期记忆意图,例如“记住我的主项目是 X”或“保存这个偏好”+- 如果 `memory_store` 已提交但抽取出 0 条记忆,应检查 OpenViking 服务端抽取模型/配置;显式路径已经触发抽取,但 extractor 没有产出记忆+### `compact()` 负责什么`compact()` 走的是另一条更严格的同步边界:@@ -222,7 +235,7 @@ preflight 阶段的 `assemble()` 并不是简单地把旧聊天记录塞回来这套插件除了自动行为,还直接暴露了 7 个工具:- `memory_recall`:显式检索长期记忆-- `memory_store`:把文本写入 OpenViking session 并立即触发 commit+- `memory_store`:把明确的长期事实写入 OpenViking session 并立即触发 commit- `memory_forget`:按 URI 删除,或先搜索再删除唯一高置信候选- `ov_archive_expand`:展开某个 archive 的原始消息- `add_resource`:把文档、目录、URL 或 Git 仓库导入为 OpenViking resource@@ -233,7 +246,7 @@ preflight 阶段的 `assemble()` 并不是简单地把旧聊天记录塞回来- 自动 recall 解决"模型不知道该先查什么"的默认场景。- `memory_recall` 给模型一个显式补查入口。-- `memory_store` 适合把一段明确的重要信息立刻落入记忆管线。+- `memory_store` 适合在用户表达长期记忆意图时,把明确的重要信息立刻落入记忆管线。- `ov_archive_expand` 负责在 summary 不够细时回到 archive 级原文。- `add_resource` 让 agent 在用户明确提出文档或仓库导入需求时直接完成操作,不要求用户记住 slash command。- `add_skill` 把 skill 导入 OpenViking,`add_resource` 把文档、目录、URL 或 Git 仓库导入为 resource。diff --git a/examples/openclaw-plugin/index.ts b/examples/openclaw-plugin/index.tsindex 733440d48..4b88e80a6 100644--- a/examples/openclaw-plugin/index.ts+++ b/examples/openclaw-plugin/index.ts@@ -1198,7 +1198,7 @@ const contextEnginePlugin = {name: "memory_store",label: "Memory Store (OpenViking)",description:- "Store text in OpenViking memory pipeline by writing to a session and running memory extraction.",+ "Store text in OpenViking memory pipeline by writing to a session and running memory extraction. Use when the user explicitly asks to remember, save, or store an important long-term fact, preference, project, or decision; automatic capture is threshold/commit dependent.",parameters: Type.Object({text: Type.String({ description: "Information to store as memory source text" }),role: Type.Optional(Type.String({ description: "Session role, default user" })),diff --git a/examples/openclaw-plugin/skills/install-openviking-memory/SKILL.md b/examples/openclaw-plugin/skills/install-openviking-memory/SKILL.mdindex 0bc32c86d..41fb4e078 100644--- a/examples/openclaw-plugin/skills/install-openviking-memory/SKILL.md+++ b/examples/openclaw-plugin/skills/install-openviking-memory/SKILL.md@@ -413,20 +413,22 @@ Expected output:> (CN) 🎉 全部搞定!OpenViking 长期记忆已经接好了。>> 工作方式:-> - **每一轮**:你的对话会被自动归档到 OpenViking session 里-> - **`/compact` 时**:归档消息会被抽取成长期记忆,写到 `~/.openviking/data/` 下+> - **每一轮**:你的对话会被自动追加到 OpenViking session 里;自动抽取依赖阈值 commit 或 `/compact`+> - **明确要记住时**:如果你说“记住/保存/存一下”某个长期事实,我会用 `memory_store` 立即提交到记忆管线+> - **`/compact` 时**:待提交的 session 消息会被抽取成长期记忆,写到 `~/.openviking/data/` 下> - **后续会话**:每次回复前我都会自动搜一下相关记忆并带进上下文>-> 想验证一下吗?跟我聊几句包含可记忆事实的话(例如"我的邮箱是 [email protected]"),然后调一下 `/compact`,再开新对话问"我的邮箱是?",应该就能召回了。+> 想验证一下吗?可以直接说“记住我的邮箱是 [email protected]”,让我通过 `memory_store` 立即提交;或者先聊几句包含可记忆事实的话,再调一下 `/compact`。之后开新对话问“我的邮箱是?”,应该就能召回了。> (EN) 🎉 All set! OpenViking long-term memory is connected.>> How it works:-> - **Every turn**: our messages are auto-archived into an OpenViking session-> - **On `/compact`**: archived messages are extracted into long-term memories under `~/.openviking/data/`+> - **Every turn**: our messages are appended to an OpenViking session; automatic extraction depends on a threshold commit or `/compact`+> - **Explicit remember requests**: if you ask me to remember/save/store a long-term fact, I can use `memory_store` to commit it immediately+> - **On `/compact`**: pending session messages are extracted into long-term memories under `~/.openviking/data/`> - **Future sessions**: relevant memories are auto-retrieved and injected before my replies>-> Want to verify? Tell me a few facts (e.g. "my email is [email protected]"), run `/compact`, then start a new chat and ask "what's my email?" — it should recall.+> Want to verify? Say "remember my email is [email protected]" so I can commit it via `memory_store`, or tell me a few memory-worthy facts and run `/compact`. Then start a new chat and ask "what's my email?" — it should recall.---@@ -434,15 +436,25 @@ Expected output:## How It Works-The context-engine pipeline has three distinct stages — keep them apart, especially when telling users when memories actually appear in `~/.openviking/data/`:+The context-engine pipeline has three distinct stages plus one explicit write path — keep them apart, especially when telling users when memories actually appear in `~/.openviking/data/`:-- **Archive / capture (context-engine `afterTurn`)**: at the end of a user turn, the plugin commits user/assistant messages to the OpenViking session via `POST /api/v1/sessions/.../messages`. This is **archive only** — no memory extraction yet. You'll see session message counts grow on the server, but no new files under `viking://user/.../memories/`.-- **Memory extraction (on `/compact`)**: memory extraction runs when the user invokes OpenClaw's `/compact` command. The server-side extraction pipeline reads the archived session and writes new memories. The plugin's `after_compaction` hook is currently reserved; the extraction itself is driven by the server. **No `/compact`, no new memory files.**+- **Archive / capture (context-engine `afterTurn`)**: at the end of a user turn, the plugin appends user/assistant messages to the OpenViking session via `POST /api/v1/sessions/.../messages`. This is **session capture only** unless `pending_tokens` crosses `commitTokenThreshold`; below the threshold, no memory extraction runs yet. You'll see session message counts grow on the server, but no new files under `viking://user/.../memories/`.+- **Memory extraction (threshold commit or `/compact`)**: memory extraction runs after a session commit. The commit can be triggered asynchronously when `afterTurn` crosses `commitTokenThreshold`, synchronously when the user invokes OpenClaw's `/compact` command, or explicitly by `memory_store`. The server-side extraction pipeline reads the archived session and writes new memories.- `captureMode: "semantic"` (default): server extraction pipeline filters all qualifying text.- `captureMode: "keyword"`: only text matching trigger words (e.g. "remember", "preference") is considered.- **Auto-Recall (context-engine `assemble()`)**: before prompt context is assembled, the plugin queries OpenViking for relevant memories and injects them into context. Recall works even when there are no extracted memories yet — you just won't see anything come back.-**Practical implication for testing**: if you write down a fact and immediately try to recall it without `/compact`, the plugin will only retrieve it as recent session context (archived messages), not as a long-term memory. To verify long-term memory cross-session, you must run `/compact` first.+**Practical implication for testing**: if you write down a short fact and immediately try to recall it without a threshold commit, `/compact`, or `memory_store`, the plugin may only retrieve it as recent session context, not as a long-term memory. To verify long-term memory cross-session deterministically, run `/compact` or use `memory_store` for the fact being tested.++### Explicit long-term memory writes++Auto-capture is best-effort and commit-dependent. When the user explicitly says to remember, save, or store an important long-term fact, preference, project, or decision, the agent should call `memory_store` instead of waiting for ordinary auto-capture.++Use `memory_store` as the integration-side reliable path for durable-memory intent:++- It writes the supplied text into an OpenViking session and calls `commit(wait=true)`.+- It complements auto-capture; it does not replace normal session capture.+- If it commits but extracts 0 memories, the explicit path has done its job. Treat that as a server-side extraction/model/configuration issue and check OpenViking logs.## Available Tools@@ -467,6 +479,8 @@ Example: user asks "What programming language did I say I like?"| `role` | No | Session role (default `user`) || `sessionId` | No | Existing OpenViking session ID |+Use this when the user explicitly asks to remember/save/store a long-term fact, preference, project, or decision.+Example: user says "Remember my email is [email protected]".### `memory_forget` — Delete Memories@@ -495,7 +509,7 @@ These are the keys under `plugins.entries.openviking.config` in `openclaw.json`.| `userId` | — | Required when `apiKey` is a root key. || `targetUri` | `viking://user/memories` | Default search scope URI. || `timeoutMs` | (plugin default) | HTTP timeout for OpenViking calls. |-| `autoCapture` | `true` | Auto-archive turn messages to OpenViking session at `afterTurn` (extraction itself runs on `/compact`, not here). |+| `autoCapture` | `true` | Auto-append turn messages to the OpenViking session at `afterTurn`; extraction runs only after a threshold commit, `/compact`, or explicit `memory_store`. || `captureMode` | `"semantic"` | Filter mode used by the server-side extraction pipeline: `semantic` or `keyword`. || `captureMaxLength` | `24000` | Max text length per archived turn. || `autoRecall` | `true` | Auto-recall and inject memories before reply. |diff --git a/examples/openclaw-plugin/tests/ut/tools.test.ts b/examples/openclaw-plugin/tests/ut/tools.test.tsindex 01ab88d87..03415797e 100644--- a/examples/openclaw-plugin/tests/ut/tools.test.ts+++ b/examples/openclaw-plugin/tests/ut/tools.test.ts@@ -315,6 +315,8 @@ describe("Tool: memory_store (behavioral)", () => {expect(store).toBeDefined();expect(store!.name).toBe("memory_store");expect(store!.description).toContain("Store text");+ expect(store!.description).toContain("explicitly asks to remember");+ expect(store!.description).toContain("threshold/commit dependent");});it("uses requesterSenderId to populate role_id for user writes", async () => {