Skip to content

Self-evolving Context Database for AI Agents. Unify Agent Memory, Knowledge RAG and Skills.

feat(openclaw): add experience memory tools (#3827)

agent61c42e3bb015
diff --git a/examples/openclaw-plugin/README.md b/examples/openclaw-plugin/README.md
index 634005472..f50882025 100644
--- a/examples/openclaw-plugin/README.md
+++ b/examples/openclaw-plugin/README.md
@@ -46,6 +46,8 @@ Once installed, the plugin provides these agent tools:
| `ov_read` | Read the full original content of one exact OpenViking URI |
| `ov_multi_read` | Read the full original content of multiple OpenViking URIs |
| `ov_list` | List OpenViking directories after search to inspect sibling chunks and overview files |
+| `search_experience` | Search reusable execution experiences for the current OpenViking user |
+| `read_experience` | Read one exact Experience returned by `search_experience` |
| `openviking_tool_result_read` | Restore the full original content of an externalized tool result |
| `openviking_tool_result_search` | Search inside an externalized tool result by keyword |
| `openviking_tool_result_list` | List externalized tool results in the current session |
@@ -248,6 +250,8 @@ Beyond automatic behavior, the plugin exposes these tools directly:
- `ov_read`: read one exact `viking://` URI returned by `ov_search` or `ov_list`
- `ov_multi_read`: read multiple exact `viking://` URIs, useful for an overview plus sibling chunks
- `ov_list`: list a hit's parent directory after `ov_search` to recover sibling chunks, `.overview.md`, and related split-document context
+- `search_experience`: search reusable execution experiences for the current OpenViking user
+- `read_experience`: read one exact Experience returned by `search_experience`
They serve different roles:
@@ -261,6 +265,7 @@ They serve different roles:
- `ov_read` turns a ranked hit into original evidence before answering precise documentation, codebase, configuration, or procedural questions
- `ov_multi_read` reads overview and sibling chunks together when a split document needs more context than a single hit
- `ov_list` complements `ov_search` when a ranked hit is only one chunk of a larger procedure or document
+- `search_experience` and `read_experience` provide the exact tool-call contract used by the bundled Experience Memory skill and usage reporting
`ov_archive_expand` is especially important because `assemble()` normally returns archive summaries and indexes, not the full raw transcript.
diff --git a/examples/openclaw-plugin/README_CN.md b/examples/openclaw-plugin/README_CN.md
index e954f4d5b..4dabcf51c 100644
--- a/examples/openclaw-plugin/README_CN.md
+++ b/examples/openclaw-plugin/README_CN.md
@@ -78,6 +78,8 @@ Agent 会自动完成安装 → 配置 → 重启 → 验证。详见 [INSTALL-A
| `ov_read` | 读取 `ov_search` / trace 返回的 `viking://...` OpenViking 虚拟 URI 完整内容 |
| `ov_multi_read` | 一次读取多个精确 `viking://...` URI,适合同时读取 overview 和同级切片 |
| `ov_list` | 在检索后列出 OpenViking 目录,补查同级切片和 `.overview.md` 文件 |
+| `search_experience` | 检索当前 OpenViking 用户的可复用执行经验 |
+| `read_experience` | 读取 `search_experience` 返回的单条 Experience 全文 |
| `openviking_tool_result_list` | 列出当前 session 中被外置的大工具输出 |
| `openviking_tool_result_search` | 在外置工具输出中按关键词搜索 |
| `openviking_tool_result_read` | 通过 `viking://session/.../tool-results/...` ref 分页读取外置工具输出 |
@@ -263,7 +265,7 @@ preflight 阶段的 `assemble()` 并不是简单地把旧聊天记录塞回来
## 工具层与可展开能力
-这套插件除了自动行为,默认直接暴露 12 个工具;当 `enableAddResourceTool=true` 时才额外暴露 opt-in 的 `add_resource` 导入工具。Agent 可见工具可以通过 `enabledTools` 和 `disabledTools` 灵活裁剪:
+这套插件除了自动行为,还会直接暴露一组 Agent 工具;当 `enableAddResourceTool=true` 时才额外暴露 opt-in 的 `add_resource` 导入工具。Agent 可见工具可以通过 `enabledTools` 和 `disabledTools` 灵活裁剪:
- `memory_recall`:在 memory/resource 目标上显式语义召回
- `memory_store`:把明确的长期事实写入 OpenViking session 并触发阻塞 commit/抽取
@@ -276,11 +278,13 @@ preflight 阶段的 `assemble()` 并不是简单地把旧聊天记录塞回来
- `ov_read`:读取 `ov_search` 或 recall trace 返回的 `viking://...` OpenViking 虚拟 URI 完整内容
- `ov_multi_read`:读取多个精确 `viking://...` URI,适合同时读取 overview 和同级切片
- `ov_list`:在 `ov_search` 命中后列出父目录,用来补齐同级切片、`.overview.md` 和同源文档上下文
+- `search_experience`:检索当前 OpenViking 用户的可复用执行经验
+- `read_experience`:读取 `search_experience` 返回的单条 Experience 全文
- `openviking_tool_result_list`:列出当前 session 中被外置的大工具输出
- `openviking_tool_result_search`:在外置工具输出中按关键词搜索
- `openviking_tool_result_read`:通过 ref 和 offset/limit 分页读取外置工具输出
-工具选择器支持精确工具名,也支持分组:`default`、`all`、`memory`、`resource_query`、`import`、`recall_trace`、`archive`、`tool_result`。例如,禁用记忆并只保留资源查询工具:
+工具选择器支持精确工具名,也支持分组:`default`、`all`、`memory`、`resource_query`、`experience`、`import`、`recall_trace`、`archive`、`tool_result`。例如,禁用记忆并只保留资源查询工具:
```json
{
diff --git a/examples/openclaw-plugin/config.ts b/examples/openclaw-plugin/config.ts
index 3356a9fad..2e0d13fed 100644
--- a/examples/openclaw-plugin/config.ts
+++ b/examples/openclaw-plugin/config.ts
@@ -168,6 +168,8 @@ export const OPENVIKING_DEFAULT_ENABLED_TOOL_NAMES = [
"ov_read",
"ov_multi_read",
"ov_list",
+ "search_experience",
+ "read_experience",
"memory_recall",
"ov_recall_trace",
"memory_store",
@@ -188,6 +190,7 @@ export const OPENVIKING_TOOL_GROUPS: Record<string, readonly OpenVikingToolName[
default: OPENVIKING_DEFAULT_ENABLED_TOOL_NAMES,
memory: ["memory_recall", "memory_store", "memory_forget"],
resource_query: ["ov_search", "ov_read", "ov_multi_read", "ov_list"],
+ experience: ["search_experience", "read_experience"],
import: ["add_resource", "add_skill"],
recall_trace: ["ov_recall_trace"],
archive: ["ov_archive_search", "ov_archive_expand"],
@@ -970,7 +973,7 @@ export const memoryOpenVikingConfigSchema = {
enabledTools: {
label: "Enabled Tools",
placeholder: "default",
- help: "Agent-visible tool allowlist. Accepts tool names or groups: default, all, memory, resource_query, import, recall_trace, archive, tool_result. add_resource also requires enableAddResourceTool=true.",
+ help: "Agent-visible tool allowlist. Accepts tool names or groups: default, all, memory, resource_query, experience, import, recall_trace, archive, tool_result. add_resource also requires enableAddResourceTool=true.",
advanced: true,
},
disabledTools: {
diff --git a/examples/openclaw-plugin/index.ts b/examples/openclaw-plugin/index.ts
index 822856854..2e1d57e31 100644
--- a/examples/openclaw-plugin/index.ts
+++ b/examples/openclaw-plugin/index.ts
@@ -19,6 +19,7 @@ import { registerOpenVikingCommands } from "./plugin/command-registration.js";
import { registerRecallTraceRoutes as registerRecallTraceRouteAdapters } from "./plugin/recall-trace-routes.js";
import { createOpenVikingService } from "./plugin/openviking-services.js";
import { registerOpenVikingArchiveTools } from "./plugin/openviking-archive-tools.js";
+import { registerOpenVikingExperienceTools } from "./plugin/openviking-experience-tools.js";
import { createOpenVikingImportRuntime } from "./plugin/openviking-import-runtime.js";
import { registerOpenVikingImportTools } from "./plugin/openviking-import-tools.js";
import { registerOpenVikingLifecycleHooks } from "./plugin/openviking-lifecycle-hooks.js";
@@ -280,6 +281,15 @@ const contextEnginePlugin = {
makeBypassedToolResult,
});
+ registerOpenVikingExperienceTools({
+ registerTool: registerOpenVikingTool,
+ getClient,
+ resolvePluginSessionRouting,
+ isBypassedSession,
+ makeBypassedToolResult,
+ userId: cfg.userId,
+ });
+
registerOpenVikingMemoryRecallTools({
registerTool: registerOpenVikingTool,
getClient,
diff --git a/examples/openclaw-plugin/install-manifest.json b/examples/openclaw-plugin/install-manifest.json
index c38cf077d..03708430d 100644
--- a/examples/openclaw-plugin/install-manifest.json
+++ b/examples/openclaw-plugin/install-manifest.json
@@ -41,6 +41,7 @@
".gitignore",
"skills/install-openviking-memory/SKILL.md",
"skills/openviking-context-database/SKILL.md",
+ "skills/ov-experience-memory/SKILL.md",
"INSTALL-AGENT.md"
]
},
diff --git a/examples/openclaw-plugin/openclaw.plugin.json b/examples/openclaw-plugin/openclaw.plugin.json
index cc0eeb20a..786bf47b4 100644
--- a/examples/openclaw-plugin/openclaw.plugin.json
+++ b/examples/openclaw-plugin/openclaw.plugin.json
@@ -19,6 +19,8 @@
"ov_read",
"ov_multi_read",
"ov_list",
+ "search_experience",
+ "read_experience",
"memory_recall",
"ov_recall_trace",
"memory_store",
@@ -252,7 +254,7 @@
"enabledTools": {
"label": "Enabled Tools",
"placeholder": "default",
- "help": "Agent-visible tool allowlist. Accepts tool names or groups: default, all, memory, resource_query, import, recall_trace, archive, tool_result. add_resource also requires enableAddResourceTool=true.",
+ "help": "Agent-visible tool allowlist. Accepts tool names or groups: default, all, memory, resource_query, experience, import, recall_trace, archive, tool_result. add_resource also requires enableAddResourceTool=true.",
"advanced": true
},
"disabledTools": {
diff --git a/examples/openclaw-plugin/plugin/openviking-experience-tools.ts b/examples/openclaw-plugin/plugin/openviking-experience-tools.ts
new file mode 100644
index 000000000..0211683a7
--- /dev/null
+++ b/examples/openclaw-plugin/plugin/openviking-experience-tools.ts
@@ -0,0 +1,160 @@
+import { Type } from "@sinclair/typebox";
+
+import type { FindResult } from "../client.js";
+
+const EXPERIENCE_TARGET_URI = "viking://user/memories/experiences/";
+const DEFAULT_LIMIT = 5;
+const MAX_LIMIT = 20;
+const EXPERIENCE_SIDECAR_FILENAMES = new Set([".abstract.md", ".overview.md", ".relations.json"]);
+
+export type OpenVikingExperienceToolContext = {
+ sessionKey?: string;
+ sessionId?: string;
+ agentId?: string;
+ senderId?: string;
+ requesterSenderId?: string;
+};
+
+export type OpenVikingExperienceSession = {
+ sessionId?: string;
+ sessionKey?: string;
+ ovSessionId?: string;
+ agentId: string;
+ actorPeerId?: string;
+};
+
+type OpenVikingExperienceClient = {
+ find: (
+ query: string,
+ options: { targetUri: string; limit: number; scoreThreshold?: number },
+ actorPeerId?: string,
+ ) => Promise<FindResult>;
+ read: (uri: string, actorPeerId?: string) => Promise<unknown>;
+};
+
+export type OpenVikingExperienceToolsDeps = {
+ registerTool: (toolOrFactory: unknown, opts: { name: string }) => void;
+ getClient: () => Promise<OpenVikingExperienceClient>;
+ resolvePluginSessionRouting: (ctx?: OpenVikingExperienceToolContext) => OpenVikingExperienceSession;
+ isBypassedSession: (ctx?: OpenVikingExperienceToolContext) => boolean;
+ makeBypassedToolResult: (toolName: string) => unknown;
+ userId?: string;
+};
+
+function clampLimit(value: unknown): number {
+ const parsed = Number.isFinite(Number(value)) ? Math.trunc(Number(value)) : DEFAULT_LIMIT;
+ return Math.max(1, Math.min(MAX_LIMIT, parsed));
+}
+
+function experienceRelativePath(uri: string): string {
+ return uri.match(/^viking:\/\/user\/[^/]+\/memories\/experiences\/(.+)$/)?.[1] ?? "";
+}
+
+export function isCanonicalExperienceUri(uri: unknown, expectedUserId?: string): uri is string {
+ const value = typeof uri === "string" ? uri.trim() : "";
+ if (!value || value.includes("?") || value.includes("#")) {
+ return false;
+ }
+ const owner = value.match(/^viking:\/\/user\/([^/]+)\//)?.[1] ?? "";
+ if (expectedUserId?.trim() && owner !== expectedUserId.trim()) {
+ return false;
+ }
+ const relative = experienceRelativePath(value);
+ const segments = relative.split("/");
+ const basename = segments.at(-1) ?? "";
+ return Boolean(
+ relative
+ && segments.every((segment) => segment && segment !== "." && segment !== "..")
+ && !EXPERIENCE_SIDECAR_FILENAMES.has(basename)
+ );
+}
+
+function titleFromUri(uri: string): string {
+ const basename = uri.split("/").at(-1) ?? uri;
+ const title = basename.replace(/\.md$/i, "");
+ try {
+ return decodeURIComponent(title);
+ } catch {
+ return title;
+ }
+}
+
+function jsonToolResult(payload: Record<string, unknown>): {
+ content: Array<{ type: "text"; text: string }>;
+} {
+ return {
+ content: [{ type: "text", text: JSON.stringify(payload) }],
+ };
+}
+
+export function registerOpenVikingExperienceTools(deps: OpenVikingExperienceToolsDeps): void {
+ deps.registerTool(
+ (ctx: OpenVikingExperienceToolContext) => ({
+ name: "search_experience",
+ label: "Search Experience (OpenViking)",
+ description:
+ "Search reusable task-execution experiences for the current OpenViking user. " +
+ "Use before executing operational or multi-step tasks, then call read_experience for selected results.",
+ parameters: Type.Object({
+ query: Type.String({ description: "Current task, situation, or execution problem to search for" }),
+ limit: Type.Optional(Type.Integer({
+ description: `Maximum results to return. Default: ${DEFAULT_LIMIT}; maximum: ${MAX_LIMIT}`,
+ minimum: 1,
+ maximum: MAX_LIMIT,
+ })),
+ }, { additionalProperties: false }),
+ async execute(_toolCallId: string, params: Record<string, unknown>) {
+ if (deps.isBypassedSession(ctx)) {
+ return deps.makeBypassedToolResult("search_experience");
+ }
+ const query = typeof params.query === "string" ? params.query.trim() : "";
+ if (!query) {
+ throw new Error("query is required");
+ }
+ const session = deps.resolvePluginSessionRouting(ctx);
+ const client = await deps.getClient();
+ const result = await client.find(query, {
+ targetUri: EXPERIENCE_TARGET_URI,
+ limit: clampLimit(params.limit),
+ }, session.actorPeerId);
+ const results = (result.memories ?? [])
+ .filter((item) => isCanonicalExperienceUri(item.uri, deps.userId))
+ .map((item) => ({
+ uri: item.uri,
+ title: titleFromUri(item.uri),
+ score: typeof item.score === "number" ? item.score : 0,
+ snippet: item.abstract || item.overview || "",
+ }));
+ return jsonToolResult({ results });
+ },
+ }),
+ { name: "search_experience" },
+ );
+
+ deps.registerTool(
+ (ctx: OpenVikingExperienceToolContext) => ({
+ name: "read_experience",
+ label: "Read Experience (OpenViking)",
+ description:
+ "Read the complete Markdown body of one Experience returned by search_experience and use it as execution guidance.",
+ parameters: Type.Object({
+ uri: Type.String({ description: "Exact canonical Experience URI returned by search_experience" }),
+ }, { additionalProperties: false }),
+ async execute(_toolCallId: string, params: Record<string, unknown>) {
+ if (deps.isBypassedSession(ctx)) {
+ return deps.makeBypassedToolResult("read_experience");
+ }
+ const uri = typeof params.uri === "string" ? params.uri.trim() : "";
+ if (!isCanonicalExperienceUri(uri, deps.userId)) {
+ throw new Error("uri must be a canonical OpenViking Experience URI returned by search_experience");
+ }
+ const session = deps.resolvePluginSessionRouting(ctx);
+ const client = await deps.getClient();
+ const content = await client.read(uri, session.actorPeerId);
+ const text = typeof content === "string" ? content : JSON.stringify(content, null, 2);
+ return jsonToolResult({ uri, content: text });
+ },
+ }),
+ { name: "read_experience" },
+ );
+}
diff --git a/examples/openclaw-plugin/registries/openviking-tools.ts b/examples/openclaw-plugin/registries/openviking-tools.ts
index 6bf1bc607..bca686943 100644
--- a/examples/openclaw-plugin/registries/openviking-tools.ts
+++ b/examples/openclaw-plugin/registries/openviking-tools.ts
@@ -1,6 +1,7 @@
export type OpenVikingToolGroup =
| "memory"
| "resource_query"
+ | "experience"
| "import"
| "recall_trace"
| "archive"
@@ -13,6 +14,8 @@ export type OpenVikingToolName =
| "ov_read"
| "ov_multi_read"
| "ov_list"
+ | "search_experience"
+ | "read_experience"
| "memory_recall"
| "ov_recall_trace"
| "memory_store"
@@ -44,6 +47,8 @@ export const OPENVIKING_TOOL_SPECS = [
{ name: "ov_read", group: "resource_query", defaultEnabled: true },
{ name: "ov_multi_read", group: "resource_query", defaultEnabled: true },
{ name: "ov_list", group: "resource_query", defaultEnabled: true },
+ { name: "search_experience", group: "experience", defaultEnabled: true },
+ { name: "read_experience", group: "experience", defaultEnabled: true },
{ name: "memory_recall", group: "memory", defaultEnabled: true },
{ name: "ov_recall_trace", group: "recall_trace", defaultEnabled: true },
{ name: "memory_store", group: "memory", defaultEnabled: true },
@@ -64,6 +69,7 @@ export const OPENVIKING_DEFAULT_ENABLED_TOOL_NAMES = OPENVIKING_TOOL_SPECS
const OPENVIKING_TOOL_GROUP_ORDER: readonly OpenVikingToolGroup[] = [
"memory",
"resource_query",
+ "experience",
"import",
"recall_trace",
"archive",
diff --git a/examples/openclaw-plugin/setup-helper/install.js b/examples/openclaw-plugin/setup-helper/install.js
index 652e7aca1..561af82c5 100755
--- a/examples/openclaw-plugin/setup-helper/install.js
+++ b/examples/openclaw-plugin/setup-helper/install.js
@@ -78,6 +78,7 @@ const FALLBACK_CURRENT = {
"session-transcript-repair.ts",
"runtime-utils.ts",
"commands/setup.ts",
+ "skills/ov-experience-memory/SKILL.md",
"tsconfig.json",
"package-lock.json",
".gitignore",
diff --git a/examples/openclaw-plugin/skills/ov-experience-memory/SKILL.md b/examples/openclaw-plugin/skills/ov-experience-memory/SKILL.md
new file mode 100644
index 000000000..1faa749e2
--- /dev/null
+++ b/examples/openclaw-plugin/skills/ov-experience-memory/SKILL.md
@@ -0,0 +1,156 @@
+---
+name: ov-experience-memory
+description: >
+ Use OpenViking experience memories during task execution. Search relevant
+ experiences with search_experience, read selected experiences with
+ read_experience, and leave standard tool parts in the committed session so
+ OpenViking can report recall and injection usage.
+version: 2026.7.9
+tags:
+ - openviking
+ - experience-memory
+ - agent-memory
+ - usage-reporting
+---
+
+# OpenViking Experience Memory
+
+Use this skill when the current user request starts or continues an executable
+task, especially tasks involving tools, files, code changes, data operations,
+workflow decisions, or multi-step actions.
+
+Do not use this skill for casual chat, pure explanation, or one-off factual Q&A
+that does not require operational guidance.
+
+## Runtime Contract
+
+The agent runtime must expose two tools with these exact names:
+
+- `search_experience`
+- `read_experience`
+
+OpenViking usage reporting recognizes only completed tool parts with these exact
+tool names. Calls to generic `find`, `search`, `read`, `ov_search`, or `ov_read`
+do not count as experience recall or injection events.
+
+## Tool: search_experience
+
+Purpose: search reusable execution experiences from the OpenViking experience
+library before assembling task context.
+
+Input schema:
+
+```json
+{
+ "query": "string",
+ "limit": 5
+}
+```
+
+Output schema:
+
+```json
+{
+ "results": [
+ {
+ "uri": "viking://user/<current_user_id>/memories/experiences/example.md",
+ "title": "example",
+ "score": 0.82,
+ "snippet": "Short summary or matched situation"
+ }
+ ]
+}
+```
+
+Implementation:
+
+The runtime tool calls OpenViking `POST /api/v1/search/find` with `target_uri`
+fixed to the current-user shorthand `viking://user/memories/experiences/`.
+Callers provide only `query` and optional `limit`; they cannot override or pass
+`target_uri`. OpenViking resolves the fixed shorthand against the authenticated
+request user. Return only canonical experience memory URIs for that user; never
+hardcode `default` or another user ID.
+
+Usage reporting:
+
+A completed `search_experience` tool part is counted as an experience recall
+event for every `results[].uri` value.
+
+## Tool: read_experience
+
+Purpose: read the full Markdown body of a selected experience and inject it into
+the agent prompt as task execution guidance.
+
+Input schema:
+
+```json
+{
+ "uri": "viking://user/<current_user_id>/memories/experiences/example.md"
+}
+```
+
+Output schema:
+
+```json
+{
+ "uri": "viking://user/<current_user_id>/memories/experiences/example.md",
+ "content": "Experience Markdown body"
+}
+```
+
+Implementation:
+
+Call OpenViking `GET /api/v1/content/read?uri=<encoded_uri>` for the selected
+experience URI. Always pass the canonical URI returned by `search_experience`;
+do not construct a URI with a hardcoded user ID. The returned content should be
+inserted into the prompt as operational guidance, not as user profile facts.
+
+Usage reporting:
+
+A completed `read_experience` tool part is counted as an experience injection
+event for `tool_input.uri` or `tool_output.uri`. In this design, reading an
+experience through `read_experience` means the experience was injected into the
+prompt.
+
+## Recommended Flow
+
+1. When a task begins, build a short query from the latest user instruction,
+ current plan, active skill name, and important tool/environment context.
+2. Call `search_experience` before final prompt assembly.
+3. Review returned titles/snippets and select only experiences likely to affect
+ execution.
+4. Call `read_experience` for selected experience URIs.
+5. Inject the returned Markdown into the prompt under an explicit experience
+ section.
+6. Continue task execution.
+7. Commit the session normally. The committed session must include the
+ `search_experience` and `read_experience` tool parts so OpenViking can report
+ usage.
+
+## Prompt Injection Format
+
+Use a compact and explicit block:
+
+```text
+<openviking-experience-memory>
+The following guidance was retrieved from prior task execution experience.
+Use it as operational guidance. Do not treat it as user identity or preference.
+
+<experience uri="viking://user/<current_user_id>/memories/experiences/example.md">
+...experience markdown...
+</experience>
+</openviking-experience-memory>
+```
+
+## Commit Requirements
+
+The session committed to OpenViking must preserve tool parts with:
+
+- `tool_name`
+- `tool_status`
+- `tool_input`
+- `tool_output`
+- `tool_id`
+
+Only `tool_status == "completed"` is counted. Failed, cancelled, or skipped tool
+parts are ignored by usage reporting.
diff --git a/examples/openclaw-plugin/tests/ut/openviking-experience-tools.test.ts b/examples/openclaw-plugin/tests/ut/openviking-experience-tools.test.ts
new file mode 100644
index 000000000..663b9b871
--- /dev/null
+++ b/examples/openclaw-plugin/tests/ut/openviking-experience-tools.test.ts
@@ -0,0 +1,155 @@
+import { describe, expect, it, vi } from "vitest";
+
+import {
+ isCanonicalExperienceUri,
+ registerOpenVikingExperienceTools,
+} from "../../plugin/openviking-experience-tools.js";
+
+type RegisteredTool = {
+ name: string;
+ execute: (toolCallId: string, params: Record<string, unknown>) => Promise<unknown>;
+};
+
+function createHarness(options: { bypassed?: boolean; userId?: string } = {}) {
+ const factories = new Map<string, (ctx: Record<string, unknown>) => RegisteredTool>();
+ const client = {
+ find: vi.fn(),
+ read: vi.fn(),
+ };
+ registerOpenVikingExperienceTools({
+ registerTool(factory, registration) {
+ factories.set(registration.name, factory as (ctx: Record<string, unknown>) => RegisteredTool);
+ },
+ getClient: vi.fn().mockResolvedValue(client),
+ resolvePluginSessionRouting: vi.fn().mockReturnValue({
+ agentId: "agent-main",
+ actorPeerId: "peer-main",
+ }),
+ isBypassedSession: vi.fn().mockReturnValue(options.bypassed ?? false),
+ makeBypassedToolResult: (toolName) => ({ bypassed: toolName }),
+ userId: options.userId,
+ });
+ const tool = (name: string): RegisteredTool => {
+ const factory = factories.get(name);
+ if (!factory) throw new Error(`tool ${name} was not registered`);
+ return factory({ sessionId: "session-1" });
+ };
+ return { client, factories, tool };
+}
+
+function parseTextResult(value: unknown): Record<string, unknown> {
+ const result = value as { content: Array<{ type: string; text: string }> };
+ return JSON.parse(result.content[0]!.text) as Record<string, unknown>;
+}
+
+describe("OpenViking Experience tools", () => {
+ it("registers the two standard Experience tool names", () => {
+ const { factories } = createHarness();
+ expect([...factories.keys()]).toEqual(["search_experience", "read_experience"]);
+ });
+
+ it("searches only the current-user Experience directory and returns canonical results", async () => {
+ const { client, tool } = createHarness();
+ client.find.mockResolvedValue({
+ memories: [
+ {
+ uri: "viking://user/test/memories/experiences/无订单号换货处理.md",
+ score: 0.86,
+ abstract: "先确认用户身份,再定位订单。",
+ },
+ {
+ uri: "viking://user/test/memories/experiences/.overview.md",
+ score: 0.9,
+ },
+ {
+ uri: "viking://user/test/memories/preferences/换货偏好.md",
+ score: 0.8,
+ },
+ ],
+ resources: [],
+ skills: [],
+ total: 3,
+ });
+
+ const output = await tool("search_experience").execute("call-search", {
+ query: "没有订单号时如何换货",
+ limit: 7,
+ });
+
+ expect(client.find).toHaveBeenCalledWith(
+ "没有订单号时如何换货",
+ {
+ targetUri: "viking://user/memories/experiences/",
+ limit: 7,
+ },
+ "peer-main",
+ );
+ expect(parseTextResult(output)).toEqual({
+ results: [
+ {
+ uri: "viking://user/test/memories/experiences/无订单号换货处理.md",
+ title: "无订单号换货处理",
+ score: 0.86,
+ snippet: "先确认用户身份,再定位订单。",
+ },
+ ],
+ });
+ });
+
+ it("reads a canonical Experience and preserves its URI in the tool result", async () => {
+ const { client, tool } = createHarness();
+ const uri = "viking://user/test/memories/experiences/无订单号换货处理.md";
+ client.read.mockResolvedValue("# 无订单号换货处理\n\n先验证用户身份。");
+
+ const output = await tool("read_experience").execute("call-read", { uri });
+
+ expect(client.read).toHaveBeenCalledWith(uri, "peer-main");
+ expect(parseTextResult(output)).toEqual({
+ uri,
+ content: "# 无订单号换货处理\n\n先验证用户身份。",
+ });
+ });
+
+ it("rejects non-Experience and noncanonical URIs before reading", async () => {
+ const { client, tool } = createHarness();
+ const readTool = tool("read_experience");
+
+ await expect(readTool.execute("call-read", {
+ uri: "viking://user/test/memories/preferences/换货偏好.md",
+ })).rejects.toThrow("canonical OpenViking Experience URI");
+ await expect(readTool.execute("call-read", {
+ uri: "viking://user/test/memories/experiences/a.md#approach",
+ })).rejects.toThrow("canonical OpenViking Experience URI");
+ expect(client.read).not.toHaveBeenCalled();
+ });
+
+ it("rejects another user's Experience when userId is explicitly configured", async () => {
+ const { client, tool } = createHarness({ userId: "current-user" });
+
+ await expect(tool("read_experience").execute("call-read", {
+ uri: "viking://user/other-user/memories/experiences/a.md",
+ })).rejects.toThrow("canonical OpenViking Experience URI");
+ expect(client.read).not.toHaveBeenCalled();
+ });
+
+ it("uses the standard bypass result without calling OpenViking", async () => {
+ const { client, tool } = createHarness({ bypassed: true });
+
+ await expect(tool("search_experience").execute("call-search", { query: "换货" }))
+ .resolves.toEqual({ bypassed: "search_experience" });
+ await expect(tool("read_experience").execute("call-read", {
+ uri: "viking://user/test/memories/experiences/a.md",
+ })).resolves.toEqual({ bypassed: "read_experience" });
+ expect(client.find).not.toHaveBeenCalled();
+ expect(client.read).not.toHaveBeenCalled();
+ });
+});
+
+describe("isCanonicalExperienceUri", () => {
+ it("accepts Experience files and rejects sidecars or URI aliases", () => {
+ expect(isCanonicalExperienceUri("viking://user/test/memories/experiences/a.md")).toBe(true);
+ expect(isCanonicalExperienceUri("viking://user/test/memories/experiences/.overview.md")).toBe(false);
+ expect(isCanonicalExperienceUri("viking://user/test/memories/experiences/a.md?version=1")).toBe(false);
+ expect(isCanonicalExperienceUri("viking://user/test/memories/experiences/../a.md")).toBe(false);
+ });
+});
diff --git a/examples/openclaw-plugin/tests/ut/openviking-tools-registry.test.ts b/examples/openclaw-plugin/tests/ut/openviking-tools-registry.test.ts
index ad28b1d05..b451f2b95 100644
--- a/examples/openclaw-plugin/tests/ut/openviking-tools-registry.test.ts
+++ b/examples/openclaw-plugin/tests/ut/openviking-tools-registry.test.ts
@@ -15,6 +15,8 @@ const DEFAULT_TOOL_NAMES = [
"ov_read",
"ov_multi_read",
"ov_list",
+ "search_experience",
+ "read_experience",
"memory_recall",
"ov_recall_trace",
"memory_store",
@@ -44,6 +46,7 @@ describe("openviking tool registry", () => {
default: DEFAULT_TOOL_NAMES,
memory: ["memory_recall", "memory_store", "memory_forget"],
resource_query: ["ov_search", "ov_read", "ov_multi_read", "ov_list"],
+ experience: ["search_experience", "read_experience"],
import: ["add_resource", "add_skill"],
recall_trace: ["ov_recall_trace"],
archive: ["ov_archive_search", "ov_archive_expand"],
@@ -64,4 +67,11 @@ describe("openviking tool registry", () => {
expect(memoryOpenVikingConfigSchema.parse({}).enabledTools).not.toContain("add_resource");
expect(memoryOpenVikingConfigSchema.parse({ enableAddResourceTool: true }).enabledTools).toContain("add_resource");
});
+
+ it("allows both Experience tools to be disabled as one group", () => {
+ const config = memoryOpenVikingConfigSchema.parse({ disabledTools: ["experience"] });
+
+ expect(config.enabledTools).not.toContain("search_experience");
+ expect(config.enabledTools).not.toContain("read_experience");
+ });
});
diff --git a/examples/openclaw-plugin/tests/ut/package-install-contract.test.ts b/examples/openclaw-plugin/tests/ut/package-install-contract.test.ts
index 81156ff59..6c77c9fb1 100644
--- a/examples/openclaw-plugin/tests/ut/package-install-contract.test.ts
+++ b/examples/openclaw-plugin/tests/ut/package-install-contract.test.ts
@@ -84,6 +84,15 @@ describe("OpenClaw plugin package and install contract", () => {
]));
});
+ it("ships the Experience Memory skill with source installs", () => {
+ const installManifest = readJson("install-manifest.json");
+ const installHelper = readFileSync(join(rootDir, "setup-helper/install.js"), "utf8");
+
+ expect(installManifest.files.optional).toContain("skills/ov-experience-memory/SKILL.md");
+ expect(existsSync(join(rootDir, "skills/ov-experience-memory/SKILL.md"))).toBe(true);
+ expect(installHelper).toContain('"skills/ov-experience-memory/SKILL.md"');
+ });
+
it("keeps runtime dependencies and overrides available for installed plugin loading", () => {
const packageJson = readJson("package.json");
diff --git a/examples/openclaw-plugin/tests/ut/plugin-registration.test.ts b/examples/openclaw-plugin/tests/ut/plugin-registration.test.ts
index ed9a4c5b9..2a32b53ff 100644
--- a/examples/openclaw-plugin/tests/ut/plugin-registration.test.ts
+++ b/examples/openclaw-plugin/tests/ut/plugin-registration.test.ts
@@ -98,4 +98,14 @@ describe("plugin registration", () => {
expect.any(Function),
);
});
+
+ it("registers the standard Experience tools by default", () => {
+ const api = createPluginApi({});
+
+ contextEnginePlugin.register(api as any);
+
+ const registeredNames = api.registerTool.mock.calls.map((call) => call[1]?.name);
+ expect(registeredNames).toContain("search_experience");
+ expect(registeredNames).toContain("read_experience");
+ });
});
diff --git a/examples/openclaw-plugin/tests/ut/tool-round-trip.test.ts b/examples/openclaw-plugin/tests/ut/tool-round-trip.test.ts
index f9dc9170e..7462dbffa 100644
--- a/examples/openclaw-plugin/tests/ut/tool-round-trip.test.ts
+++ b/examples/openclaw-plugin/tests/ut/tool-round-trip.test.ts
@@ -39,6 +39,43 @@ describe("extractNewTurnMessages: toolCallId propagation", () => {
}
});
+ it("preserves standard Experience calls as completed ToolParts", () => {
+ const uri = "viking://user/test/memories/experiences/无订单号换货处理.md";
+ const messages = [
+ {
+ role: "assistant",
+ content: [
+ {
+ type: "toolCall",
+ id: "call_experience_search",
+ name: "search_experience",
+ arguments: { query: "没有订单号时如何换货", limit: 5 },
+ },
+ ],
+ },
+ {
+ role: "toolResult",
+ toolCallId: "call_experience_search",
+ toolName: "search_experience",
+ content: [{ type: "text", text: JSON.stringify({ results: [{ uri }] }) }],
+ },
+ ];
+
+ const { messages: extracted } = extractNewTurnMessages(messages, 0);
+ const toolPart = extracted.flatMap((message) => message.parts).find((part) => part.type === "tool");
+
+ expect(toolPart).toMatchObject({
+ type: "tool",
+ toolCallId: "call_experience_search",
+ toolName: "search_experience",
+ toolInput: { query: "没有订单号时如何换货", limit: 5 },
+ toolStatus: "completed",
+ });
+ if (toolPart?.type === "tool") {
+ expect(JSON.parse(toolPart.toolOutput)).toEqual({ results: [{ uri }] });
+ }
+ });
+
it("sets toolCallId to undefined when original message has no toolCallId", () => {
const messages = [
{
diff --git a/examples/openclaw-plugin/tests/ut/tools.test.ts b/examples/openclaw-plugin/tests/ut/tools.test.ts
index 4ed964823..6e1313dd5 100644
--- a/examples/openclaw-plugin/tests/ut/tools.test.ts
+++ b/examples/openclaw-plugin/tests/ut/tools.test.ts
@@ -1988,10 +1988,10 @@ describe("Tool: ov_recall_trace", () => {
});
describe("Plugin registration", () => {
- it("registers all 14 default tools", () => {
+ it("registers all 16 default tools", () => {
const { api } = setupPlugin();
contextEnginePlugin.register(api as any);
- expect(api.registerTool).toHaveBeenCalledTimes(14);
+ expect(api.registerTool).toHaveBeenCalledTimes(16);
});
it("registers only resource query tools when enabledTools is resource_query", () => {