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): restore explicit memory write guidance (#2746)
Mingjian Que4ce2832c7fcc
diff --git a/examples/openclaw-plugin/README_CN.md b/examples/openclaw-plugin/README_CN.mdindex ba5d3d9ca..02afa60f2 100644--- a/examples/openclaw-plugin/README_CN.md+++ b/examples/openclaw-plugin/README_CN.md@@ -56,8 +56,9 @@ Agent 会自动完成安装 → 配置 → 重启 → 验证。详见 [INSTALL-A| 阶段 | 行为 ||------|------|-| **每轮对话后** (`afterTurn`) | 消息自动归档到 OpenViking session |-| **`/compact` 时** (`compact`) | 归档消息被抽取为长期记忆 |+| **每轮对话后** (`afterTurn`) | 新消息追加到 OpenViking session;commit/抽取由阈值触发 |+| **明确要求记住** (`memory_store`) | 重要长期事实可立即写入并提交 |+| **`/compact` 时** (`compact`) | 待提交 session 消息被 commit 并抽取为长期记忆 || **回复前** (`assemble`) | 自动检索相关记忆并注入上下文 |## 工具@@ -67,7 +68,7 @@ Agent 会自动完成安装 → 配置 → 重启 → 验证。详见 [INSTALL-A| 工具 | 用途 ||------|------|| `memory_recall` | 在 `user`、`agent`、`resource` 目标中显式语义召回 |-| `memory_store` | 将重要文本写入 session,并立即触发记忆抽取 |+| `memory_store` | 立即持久化明确的长期事实 || `memory_forget` | 按精确 URI 删除记忆,或搜索并删除唯一高置信匹配 || `ov_archive_search` | 对当前 session 已归档的原始对话消息做关键词 grep || `ov_archive_expand` | 按 archive ID 展开原始消息 |@@ -237,6 +238,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()` 走的是另一条更严格的同步边界:@@ -253,7 +266,7 @@ preflight 阶段的 `assemble()` 并不是简单地把旧聊天记录塞回来这套插件除了自动行为,默认直接暴露 12 个工具;当 `enableAddResourceTool=true` 时才额外暴露 opt-in 的 `add_resource` 导入工具。Agent 可见工具可以通过 `enabledTools` 和 `disabledTools` 灵活裁剪:- `memory_recall`:在 memory/resource 目标上显式语义召回-- `memory_store`:把文本写入 OpenViking session 并触发阻塞 commit/抽取+- `memory_store`:把明确的长期事实写入 OpenViking session 并触发阻塞 commit/抽取- `memory_forget`:按 URI 删除,或先搜索再删除唯一高置信候选- `ov_archive_search`:按关键词 grep 已归档的原始对话消息- `ov_archive_expand`:展开某个 archive 的原始消息@@ -283,7 +296,7 @@ preflight 阶段的 `assemble()` 并不是简单地把旧聊天记录塞回来- 自动 recall 解决"模型不知道该先查什么"的默认场景。- `memory_recall` 给模型一个显式补查入口。-- `memory_store` 适合把一段明确的重要信息立刻落入记忆管线。+- `memory_store` 适合在用户表达长期记忆意图时,把明确的重要信息立刻落入记忆管线。- `ov_archive_search` 和 `ov_archive_expand` 负责在 summary 不够细时回到 archive 级原文。- `ov_recall_trace` 用来解释某次召回/检索为什么命中或没有命中某些内容。- 手动 `/add-resource` 用于把文档、目录、URL 或 Git 仓库导入为 resource;Agent 可见的 `add_resource` 是 opt-in 工具,不能在搜索、检索、URI 读取或搜索结果优化阶段使用。diff --git a/examples/openclaw-plugin/plugin/openviking-memory-tools.ts b/examples/openclaw-plugin/plugin/openviking-memory-tools.tsindex 8ee346aaa..43d805080 100644--- a/examples/openclaw-plugin/plugin/openviking-memory-tools.ts+++ b/examples/openclaw-plugin/plugin/openviking-memory-tools.ts@@ -71,7 +71,7 @@ export function registerOpenVikingMemoryTools(deps: OpenVikingMemoryToolsDeps):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 17b6c7b79..06a8e0959 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 服务端被抽取成长期记忆+> - **每一轮**:你的对话会被自动追加到 OpenViking session 里;自动抽取依赖阈值 commit 或 `/compact`+> - **明确要记住时**:如果你说“记住/保存/存一下”某个长期事实,我会用 `memory_store` 立即提交到记忆管线+> - **`/compact` 时**:待提交的 session 消息会在 OpenViking 服务端被抽取成长期记忆> - **后续会话**:每次回复前我都会自动搜一下相关记忆并带进上下文>-> 想验证一下吗?跟我聊几句包含可记忆事实的话(例如"我的邮箱是 [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 on the OpenViking server+> - **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 on the OpenViking server> - **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 become searchable long-term memory on the OpenViking server:+The context-engine pipeline has three distinct stages plus one explicit write path — keep them apart, especially when telling users when memories become searchable long-term memory on the OpenViking server:-- **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@@ -468,6 +480,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@@ -578,7 +592,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/skills/openviking-context-database/SKILL.md b/examples/openclaw-plugin/skills/openviking-context-database/SKILL.mdindex 66c2d577d..7e4c289f1 100644--- a/examples/openclaw-plugin/skills/openviking-context-database/SKILL.md+++ b/examples/openclaw-plugin/skills/openviking-context-database/SKILL.md@@ -272,7 +272,7 @@ Command parsers support quoted args and flags. Resource-only flags are rejected| `configured=false` | Setup did not persist config | Re-run `openclaw openviking setup ... --json`; branch on JSON `error`. || `slotActive=false` | Another context engine owns the slot or gateway has stale state | Inspect `plugins.slots.contextEngine`; use `--force-slot` only after user confirms. || `health.ok=false` | Server unreachable or wrong `baseUrl` / key | Check `baseUrl`, network, `/health`, and auth. |-| No long-term memory after a fresh fact | `/compact` or commit/extraction has not run, or server extraction failed | Run `/compact`; check OpenViking server logs. |+| No long-term memory after a fresh fact | `/compact` or commit/extraction has not run, or server extraction failed | Use `memory_store` for explicit remember/save/store intents; otherwise run `/compact` or wait for threshold commit, then check OpenViking server logs. || Recall misses shared documents | `resource` target is not enabled | Use `memory_recall` with `resourceTypes:["resource"]` or configure `recallTargetTypes: ["resource"]`. || Summary lacks exact detail | Archive summary is too coarse | Use `ov_archive_search` with concrete keywords, then `ov_archive_expand`. || Large tool output preview is insufficient | Tool result was externalized | Use `openviking_tool_result_search/read` with the ref. |diff --git a/examples/openclaw-plugin/tests/ut/tools.test.ts b/examples/openclaw-plugin/tests/ut/tools.test.tsindex 4d50e9a7f..d04a344be 100644--- a/examples/openclaw-plugin/tests/ut/tools.test.ts+++ b/examples/openclaw-plugin/tests/ut/tools.test.ts@@ -451,6 +451,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 () => {