Skip to content

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

feat: add extensible usage reporting (#3222)

agentccc271ff27d6
diff --git a/docs/design/openviking-usage-reporter-sink-design.md b/docs/design/openviking-usage-reporter-sink-design.md
new file mode 100644
index 000000000..0989383d4
--- /dev/null
+++ b/docs/design/openviking-usage-reporter-sink-design.md
@@ -0,0 +1,223 @@
+# OpenViking Usage Reporter / Sink 技术方案
+
+## 1. 背景
+
+OpenViking 在 session commit 时会收到完整的 session messages。Agent runtime 调用 tool 后,会在 session messages 中留下 tool parts。部分 tool parts 可以表达某个记忆文件被检索、读取、注入等行为。
+
+OpenViking 需要从 session 中解析出这些使用行为,并将结构化事件交给可扩展的下游。内核不绑定具体消息队列、Webhook、日志系统或数据库,而是提供通用的 Usage Reporter / Sink 扩展机制。
+
+## 2. 业界做法
+
+这种模式是开源基础设施里常见的设计。
+
+OpenTelemetry Collector 把数据链路拆成 receivers、processors、exporters、pipelines。exporters 专门负责把数据发送到不同 backend 或 destination,例如 OTLP、Kafka、Prometheus、file 等。配置 exporter 本身不代表启用,需要在 pipeline 中声明。
+
+参考:https://opentelemetry.io/docs/collector/configuration/
+
+Vector 使用 sinks 概念,把 observability data 投递到不同目的地,例如 File、HTTP、Kafka、S3、ClickHouse、Prometheus remote write 等。
+
+参考:https://vector.dev/docs/reference/configuration/sinks/
+
+Fluent Bit 使用 Outputs 概念。官方定义里,Outputs 用来定义数据目的地,常见目的地包括远端服务、本地文件系统或标准接口,并且 Outputs 以 plugin 形式实现。
+
+参考:https://docs.fluentbit.io/manual/data-pipeline/outputs
+
+所以 OpenViking 采用“核心定义事件 + 插件式 Sink 输出”是合理的。它的核心价值是把“事件产生”和“事件去哪”解耦。
+
+## 3. 设计目标
+
+- OpenViking 内核只定义 UsageEvent 标准结构。
+- OpenViking 内核负责从 session commit 中解析 UsageEvent。
+- OpenViking 内核不绑定具体下游及其依赖。
+- 部署方可以通过自定义 Sink 接入目标系统。
+- Sink 失败默认不影响 session commit。
+- 默认不上报完整 session,只上报结构化事件,并保留定位原始 session ToolPart 所需的证据信息。
+
+## 4. 总体架构
+
+数据流:
+
+```text
+Agent runtime 调用 tool
+-> session message 留下 tool part
+-> client 上传 session 并 commit
+-> OpenViking archive session
+-> UsageExtractor 从 session messages 解析 UsageEvent
+-> UsageReporter 分发 UsageEvent
+-> UsageSink 写入目标系统
+```
+
+模块拆分:
+
+```text
+UsageExtractor:负责从 session 里解析事件
+UsageEvent:标准结构化事件
+UsageReporter:负责分发事件
+UsageSink:负责写入不同下游
+```
+
+## 5. UsageEvent
+
+UsageEvent 是 OpenViking 内核和外部 Sink 之间的稳定协议。
+
+示例:
+
+```json
+{
+ "schema_version": "v1",
+ "event_id": "ue_<sha256>",
+ "event_type": "memory.injected",
+ "resource_uri": "viking://user/test/memories/experiences/xxx.md",
+ "resource_type": "experience",
+ "account_id": "new",
+ "user_id": "test",
+ "session_id": "510bb5f9-4671-498e-adf4-27bb1b3691fe",
+ "task_id": "b174eb56-e7d4-4fee-98a6-c53c0ddf62ed",
+ "occurred_at": "2026-07-09T12:00:00Z",
+ "evidence": {
+ "archive_uri": "viking://user/test/sessions/510bb5f9/history/archive_001",
+ "message_id": "msg_xxx",
+ "tool_call_id": "call_xxx",
+ "tool_name": "read_experience"
+ },
+ "attributes": {}
+}
+```
+
+默认只上报结构化事件,不上报完整 session 内容。
+
+`resource_uri` 和 `resource_type` 描述被使用的资源,不限定为记忆文件;事件类型特有的数据写入 `attributes`。当前 `MemoryUsageExtractor` 只接受属于 `UsageContext.user_id` 的规范 experience URI,其他用户 URI 不生成 UsageEvent。ToolPart 必须包含非空 `tool_id`,无法稳定标识具体调用的 ToolPart 不进入统计。
+
+UsageEvent 是可独立传输和消费的完整事件。`UsageContext` 只用于 Extractor 构造事件,不再重复传给 Sink。
+
+## 6. UsageSink 机制
+
+OpenViking 开源包只定义 Sink 抽象:
+
+```python
+class UsageSink:
+ async def write(self, *, events: list[UsageEvent]) -> None:
+ ...
+```
+
+具体 Sink 作为外部扩展,通过 `class_path` 动态加载。
+
+配置示例:
+
+```yaml
+server:
+ usage_reporter:
+ enabled: true
+ sinks:
+ - type: custom
+ class_path: example_usage.custom_sink.CustomUsageSink
+ config:
+ endpoint: https://usage.example.com/events
+```
+
+OpenViking 用 `importlib` 动态加载:
+
+```python
+import importlib
+
+def load_class(class_path: str):
+ module_name, class_name = class_path.rsplit(".", 1)
+ module = importlib.import_module(module_name)
+ return getattr(module, class_name)
+```
+
+只有配置了该 Sink 时才 import 对应模块。OpenViking 内核不 import 或安装具体下游依赖。
+
+每个 Sink 的 `write()` 调用最多等待 5 秒。超时或异常只记录日志,不影响其他 Sink。Reporter 在应用生命周期内只创建一次,应用退出时调用 Sink 可选的 `close()` 方法。同步和异步 `close()` 均受同一超时限制;同步 hook 在独立 daemon 线程中执行,超时后不会阻塞事件循环、后续 Sink 清理或进程退出。
+
+## 7. 配置设计
+
+默认关闭:
+
+```yaml
+server:
+ usage_reporter:
+ enabled: false
+```
+
+自定义 Sink:
+
+```yaml
+server:
+ usage_reporter:
+ enabled: true
+ sinks:
+ - type: custom
+ class_path: example_usage.custom_sink.CustomUsageSink
+ config:
+ endpoint: https://usage.example.com/events
+```
+
+## 8. 对 OpenViking 的侵入
+
+侵入点控制在 4 个地方。
+
+1. 新增 config
+
+增加 `usage_reporter` 配置段。
+
+2. 新增数据模型
+
+增加 `UsageEvent`、`UsageContext`。
+
+3. session commit 增加 hook
+
+在 session archive 成功后触发:
+
+```text
+archive session success
+-> usage extractor
+-> usage reporter
+```
+
+4. 新增 reporter/sink 模块
+
+新增通用扩展点和 custom sink 动态加载能力。
+
+不侵入的地方:
+
+- 不改 `find/search` 语义。
+- 不改 `read` 语义。
+- 不把具体下游写死进 session commit。
+- 不默认上传完整 session。
+- 不强制写 MEMORY_FIELDS。
+- 不强制写 search_tags。
+- 不影响 snapshot。
+- Sink 调用具有 5 秒超时边界,失败不会中断 phase2。
+
+整体侵入属于低到中等,核心主链路只增加一个旁路 hook。
+
+## 9. 可靠性策略
+
+Usage Reporter 采用 best-effort 投递语义:
+
+- Sink 成功:正常返回。
+- Sink 失败或超时:记录日志,不影响 session commit,也不自动重试。
+- 多个 Sink 相互隔离,某个 Sink 失败不影响其他 Sink。
+- Sink 失败时事件可能丢失,因此本机制不保证 at-least-once。
+- 如果 Sink 已写入成功,但进程在 phase2 写入完成标记前退出,phase2 恢复执行时可能重复发送同一事件。
+- 每个事件包含稳定的 `event_id`。Sink 可将其作为 Kafka message key,消费端可按 `event_id` 去重。
+- `event_id` 只用于识别重复事件,不代表事件一定成功送达。
+
+`event_id` 为以下字段规范序列化后的 SHA-256:
+
+```text
+schema_version
++ event_type
++ account_id
++ user_id
++ session_id
++ task_id
++ evidence.archive_uri
++ evidence.tool_call_id
++ resource_uri
+```
+
+`occurred_at`、`message_id` 和 `attributes` 不参与计算,避免重放时间差或附加属性变化破坏幂等性。同一 archive 中同一 tool call 对同一资源产生的事件,在 phase2 重放后仍得到相同 `event_id`。
+
+如果后续需要可靠投递,需要增加持久化 outbox、失败重试和发送确认机制。
diff --git a/examples/claude-code-memory-plugin/scripts/shared/mcp-proxy-core.mjs b/examples/claude-code-memory-plugin/scripts/shared/mcp-proxy-core.mjs
index cb09673d6..4fc2483cb 100644
--- a/examples/claude-code-memory-plugin/scripts/shared/mcp-proxy-core.mjs
+++ b/examples/claude-code-memory-plugin/scripts/shared/mcp-proxy-core.mjs
@@ -142,6 +142,7 @@ export function createOpenVikingMcpProxy({
readConfig,
loggerFactory,
fetchImpl = globalThis.fetch,
+ localToolProvider = null,
} = {}) {
if (typeof fetchImpl !== "function") {
throw new Error("global fetch is required; use Node.js 18 or newer");
@@ -179,6 +180,43 @@ export function createOpenVikingMcpProxy({
} catch { /* debug logging must never affect protocol IO */ }
}
+ function localTools() {
+ if (!localToolProvider || typeof localToolProvider.listTools !== "function") return [];
+ const tools = localToolProvider.listTools();
+ return Array.isArray(tools) ? tools : [];
+ }
+
+ function appendLocalTools(message, outbound) {
+ if (message.method !== "tools/list" || !Array.isArray(outbound?.result?.tools)) {
+ return outbound;
+ }
+ const additions = localTools().filter((tool) => tool?.name);
+ if (additions.length === 0) return outbound;
+ const localNames = new Set(additions.map((tool) => tool.name));
+ const upstreamTools = outbound.result.tools.filter((tool) => !localNames.has(tool?.name));
+ return {
+ ...outbound,
+ result: {
+ ...outbound.result,
+ tools: [...upstreamTools, ...additions],
+ },
+ };
+ }
+
+ async function callLocalTool(message) {
+ if (
+ message.method !== "tools/call"
+ || !localToolProvider
+ || typeof localToolProvider.callTool !== "function"
+ ) {
+ return null;
+ }
+ const name = message.params?.name;
+ if (!localTools().some((tool) => tool?.name === name)) return null;
+ reloadIfCredentialFilesChanged("local_tool_call");
+ return localToolProvider.callTool(message.params, { config: proxyConfig });
+ }
+
function reloadConfig(reason) {
proxyConfig = readConfig();
logger = loggerFactory("mcp-proxy", proxyConfig);
@@ -381,6 +419,13 @@ export function createOpenVikingMcpProxy({
}
try {
+ const localResult = await callLocalTool(message);
+ if (localResult !== null) {
+ if (expectsResponse) {
+ await writeMessage({ jsonrpc: "2.0", id: message.id, result: localResult });
+ }
+ return;
+ }
const send = sendWithRetry(message, { expectsResponse });
if (message.method === "initialize") {
initializeInFlight = send
@@ -396,7 +441,7 @@ export function createOpenVikingMcpProxy({
return;
}
for (const outbound of result.messages) {
- await writeMessage(outbound);
+ await writeMessage(appendLocalTools(message, outbound));
}
} catch (err) {
if (expectsResponse) {
diff --git a/examples/codex-memory-plugin/.codex-plugin/plugin.json b/examples/codex-memory-plugin/.codex-plugin/plugin.json
index bca752031..109f7801a 100644
--- a/examples/codex-memory-plugin/.codex-plugin/plugin.json
+++ b/examples/codex-memory-plugin/.codex-plugin/plugin.json
@@ -1,6 +1,6 @@
{
"name": "openviking-memory",
- "version": "0.7.3",
+ "version": "0.7.4",
"description": "Long-term semantic memory for Codex, powered by OpenViking. Recall on UserPromptSubmit, incremental add_message on Stop (per turn), commit on PreCompact, and active-window heuristic + idle-TTL sweep on SessionStart (source=startup|clear). Includes a local stdio MCP proxy that reads OpenViking credentials from env/ovcli.conf.",
"author": {
"name": "OpenViking",
@@ -30,7 +30,8 @@
"Pre-compaction memory extraction",
"Session archive search and original-text read-back",
"Resource ingestion for RAG (add_resource)",
- "Explicit MCP tools for retrieval, memory, resources, watches, filesystem, and code navigation"
+ "Explicit MCP tools for retrieval, memory, resources, watches, filesystem, and code navigation",
+ "Experience Memory skill with dedicated search_experience and read_experience tools"
],
"websiteURL": "https://github.com/volcengine/OpenViking"
}
diff --git a/examples/codex-memory-plugin/scripts/capture-utils.mjs b/examples/codex-memory-plugin/scripts/capture-utils.mjs
index 0d3b81e5d..c681420a3 100644
--- a/examples/codex-memory-plugin/scripts/capture-utils.mjs
+++ b/examples/codex-memory-plugin/scripts/capture-utils.mjs
@@ -1 +1,109 @@
+import {
+ extractCaptureTurns as extractSharedCaptureTurns,
+} from "./shared/capture-utils.mjs";
+
export * from "./shared/capture-utils.mjs";
+
+function mcpResultText(result) {
+ const ok = result?.Ok;
+ if (Array.isArray(ok?.content)) {
+ const text = ok.content
+ .filter((part) => part?.type === "text" && typeof part.text === "string")
+ .map((part) => part.text)
+ .join("\n");
+ if (text) return text;
+ }
+ if (typeof ok === "string") return ok;
+ if (ok != null) return JSON.stringify(ok);
+ const error = result?.Err;
+ if (typeof error === "string") return error;
+ return error == null ? "" : JSON.stringify(error);
+}
+
+function normalizeCodexMcpToolEvents(rolloutEntries) {
+ return (rolloutEntries || []).flatMap((entry) => {
+ const payload = entry?.payload;
+ if (payload?.type !== "mcp_tool_call_end") return [entry];
+
+ const callId = payload.call_id;
+ const toolName = payload.invocation?.tool;
+ if (!callId || !toolName) return [entry];
+
+ const call = {
+ payload: {
+ type: "function_call",
+ id: callId,
+ name: toolName,
+ arguments: payload.invocation?.arguments || {},
+ },
+ };
+ const output = mcpResultText(payload.result);
+ const completed = (
+ Object.prototype.hasOwnProperty.call(payload.result || {}, "Ok")
+ && payload.result?.Ok?.isError !== true
+ );
+ const result = {
+ payload: {
+ type: "function_call_output",
+ call_id: callId,
+ ...(completed ? { output } : { error: output || "MCP tool call failed" }),
+ },
+ };
+ return [call, result];
+ });
+}
+
+function parseJsonObject(value) {
+ if (typeof value !== "string" || !value.trim()) return null;
+ try {
+ const parsed = JSON.parse(value);
+ return parsed && typeof parsed === "object" && !Array.isArray(parsed) ? parsed : null;
+ } catch {
+ return null;
+ }
+}
+
+function collectExperienceUsageMetadata(rolloutEntries) {
+ const metadata = new Map();
+ for (const entry of rolloutEntries || []) {
+ const payload = entry?.payload;
+ if (payload?.type !== "mcp_tool_call_end" || !payload.call_id) continue;
+ const toolName = payload.invocation?.tool;
+ if (toolName !== "search_experience" && toolName !== "read_experience") continue;
+
+ const item = {
+ toolName,
+ toolInput: payload.invocation?.arguments || {},
+ };
+ if (toolName === "search_experience") {
+ const output = parseJsonObject(mcpResultText(payload.result));
+ const results = Array.isArray(output?.results) ? output.results : [];
+ item.compactOutput = JSON.stringify({
+ results: results
+ .map((result) => ({ uri: String(result?.uri || "").trim() }))
+ .filter((result) => result.uri),
+ });
+ }
+ metadata.set(payload.call_id, item);
+ }
+ return metadata;
+}
+
+export function extractCaptureTurns(rolloutEntries, cfg = {}) {
+ const usageMetadata = collectExperienceUsageMetadata(rolloutEntries);
+ const turns = extractSharedCaptureTurns(normalizeCodexMcpToolEvents(rolloutEntries), cfg);
+ return turns.map((turn) => ({
+ ...turn,
+ parts: turn.parts.map((part) => {
+ if (part?.tool_status !== "completed" || !part.tool_id) return part;
+ const metadata = usageMetadata.get(part.tool_id);
+ if (!metadata) return part;
+
+ const updated = { ...part, tool_input: metadata.toolInput };
+ if (metadata.toolName === "search_experience" && !parseJsonObject(part.tool_output)) {
+ updated.tool_output = metadata.compactOutput;
+ }
+ return updated;
+ }),
+ }));
+}
diff --git a/examples/codex-memory-plugin/scripts/capture-utils.test.mjs b/examples/codex-memory-plugin/scripts/capture-utils.test.mjs
new file mode 100644
index 000000000..2d7b81c46
--- /dev/null
+++ b/examples/codex-memory-plugin/scripts/capture-utils.test.mjs
@@ -0,0 +1,188 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+
+import { extractCaptureTurns } from "./capture-utils.mjs";
+
+test("captures Codex mcp_tool_call_end as standard tool parts", () => {
+ const results = {
+ results: [
+ {
+ uri: "viking://user/test/memories/experiences/无订单号换货处理.md",
+ title: "无订单号换货处理",
+ },
+ ],
+ };
+ const turns = extractCaptureTurns(
+ [
+ {
+ type: "event_msg",
+ payload: {
+ type: "mcp_tool_call_end",
+ call_id: "exec-search-1",
+ invocation: {
+ server: "openviking-memory",
+ tool: "search_experience",
+ arguments: { query: "无订单号换货" },
+ },
+ result: {
+ Ok: {
+ content: [{ type: "text", text: JSON.stringify(results) }],
+ },
+ },
+ },
+ },
+ ],
+ {
+ captureAssistantTurns: true,
+ captureToolMaxChars: 2000,
+ captureMaxLength: 24000,
+ },
+ );
+
+ assert.deepEqual(turns, [
+ {
+ role: "assistant",
+ text: "[tool-call search_experience] {\"query\":\"无订单号换货\"}",
+ parts: [
+ {
+ type: "tool",
+ tool_id: "exec-search-1",
+ tool_name: "search_experience",
+ tool_status: "running",
+ tool_input: { query: "无订单号换货" },
+ },
+ ],
+ },
+ {
+ role: "user",
+ text: `[tool-result] ${JSON.stringify(results)}`,
+ parts: [
+ {
+ type: "tool",
+ tool_id: "exec-search-1",
+ tool_name: "search_experience",
+ tool_status: "completed",
+ tool_input: { query: "无订单号换货" },
+ tool_output: JSON.stringify(results),
+ },
+ ],
+ },
+ ]);
+});
+
+test("keeps MCP tool-level errors out of completed Experience tool parts", () => {
+ const uri = "viking://user/test/memories/experiences/a.md";
+ const turns = extractCaptureTurns(
+ [
+ {
+ type: "event_msg",
+ payload: {
+ type: "mcp_tool_call_end",
+ call_id: "exec-read-error",
+ invocation: {
+ server: "openviking-memory",
+ tool: "read_experience",
+ arguments: { uri },
+ },
+ result: {
+ Ok: {
+ isError: true,
+ content: [{ type: "text", text: "OpenViking request failed (HTTP 500)" }],
+ },
+ },
+ },
+ },
+ ],
+ {
+ captureAssistantTurns: true,
+ captureToolMaxChars: 2000,
+ captureMaxLength: 24000,
+ },
+ );
+
+ const parts = turns.flatMap((turn) => turn.parts);
+ assert.deepEqual(parts.map((part) => part.tool_status), ["running", "error"]);
+ assert.equal(parts.some((part) => part.tool_status === "completed"), false);
+});
+
+test("preserves Experience usage metadata when Codex truncates a long MCP result", () => {
+ const uri = "viking://user/test/memories/experiences/long-experience.md";
+ const turns = extractCaptureTurns(
+ [
+ {
+ type: "event_msg",
+ payload: {
+ type: "mcp_tool_call_end",
+ call_id: "exec-read-long",
+ invocation: {
+ server: "openviking-memory",
+ tool: "read_experience",
+ arguments: { uri },
+ },
+ result: {
+ Ok: {
+ content: [
+ {
+ type: "text",
+ text: JSON.stringify({ uri, content: "x".repeat(3000) }),
+ },
+ ],
+ },
+ },
+ },
+ },
+ ],
+ {
+ captureAssistantTurns: true,
+ captureToolMaxChars: 2000,
+ captureMaxLength: 24000,
+ },
+ );
+
+ const completed = turns
+ .flatMap((turn) => turn.parts)
+ .find((part) => part.tool_status === "completed");
+ assert.deepEqual(completed.tool_input, { uri });
+});
+
+test("keeps search Experience URIs parseable when snippets exceed the capture limit", () => {
+ const uri = "viking://user/test/memories/experiences/long-search-result.md";
+ const turns = extractCaptureTurns(
+ [
+ {
+ type: "event_msg",
+ payload: {
+ type: "mcp_tool_call_end",
+ call_id: "exec-search-long",
+ invocation: {
+ server: "openviking-memory",
+ tool: "search_experience",
+ arguments: { query: "换货" },
+ },
+ result: {
+ Ok: {
+ content: [
+ {
+ type: "text",
+ text: JSON.stringify({
+ results: [{ uri, title: "换货经验", snippet: "x".repeat(3000) }],
+ }),
+ },
+ ],
+ },
+ },
+ },
+ },
+ ],
+ {
+ captureAssistantTurns: true,
+ captureToolMaxChars: 2000,
+ captureMaxLength: 24000,
+ },
+ );
+
+ const completed = turns
+ .flatMap((turn) => turn.parts)
+ .find((part) => part.tool_status === "completed");
+ assert.deepEqual(JSON.parse(completed.tool_output), { results: [{ uri }] });
+});
diff --git a/examples/codex-memory-plugin/scripts/marketplace.test.mjs b/examples/codex-memory-plugin/scripts/marketplace.test.mjs
index a8691009a..f851fa6c4 100644
--- a/examples/codex-memory-plugin/scripts/marketplace.test.mjs
+++ b/examples/codex-memory-plugin/scripts/marketplace.test.mjs
@@ -119,6 +119,30 @@ test("required plugin files are present", () => {
}
});
+test("plugin bundles the Experience Memory skill", () => {
+ const skillPath = join(pluginDir, "skills", "ov-experience-memory", "SKILL.md");
+ assert.ok(existsSync(skillPath), `missing bundled skill: ${skillPath}`);
+ const content = readFileSync(skillPath, "utf-8");
+ assert.match(content, /^---[\s\S]*name:\s*ov-experience-memory[\s\S]*---/);
+ assert.match(content, /`search_experience`/);
+ assert.match(content, /`read_experience`/);
+});
+
+test("Experience Memory skill examples match the search_experience input schema", () => {
+ const skillPaths = [
+ join(pluginDir, "skills", "ov-experience-memory", "SKILL.md"),
+ join(repoRoot, "examples", "skills", "ov-experience-memory", "SKILL.md"),
+ ];
+ for (const skillPath of skillPaths) {
+ const content = readFileSync(skillPath, "utf-8");
+ const section = content.match(/## Tool: search_experience([\s\S]*?)## Tool: read_experience/)?.[1];
+ assert.ok(section, `missing search_experience section in ${skillPath}`);
+ const inputExample = section.match(/Input schema:\s*```json\s*([\s\S]*?)```/)?.[1];
+ assert.ok(inputExample, `missing search_experience input example in ${skillPath}`);
+ assert.deepEqual(Object.keys(JSON.parse(inputExample)).sort(), ["limit", "query"]);
+ }
+});
+
test("plugin.json does not describe legacy MCP tool names", () => {
const manifest = readJson(manifestPath);
const interfaceText = JSON.stringify(manifest.interface || {});
@@ -157,6 +181,12 @@ test(".mcp.json starts the stdio MCP proxy from the plugin root", () => {
execFileSync("node", ["--check", join(pluginDir, "servers", "mcp-proxy.mjs")], { stdio: "pipe" });
});
+test("Codex MCP entrypoint wires the Experience tool provider", () => {
+ const entrypoint = readFileSync(join(pluginDir, "servers", "mcp-proxy.mjs"), "utf-8");
+ assert.match(entrypoint, /createExperienceToolProvider/);
+ assert.match(entrypoint, /localToolProvider/);
+});
+
test("canonical MCP tool list matches server registrations", () => {
const source = readFileSync(mcpEndpointPath, "utf-8");
const registered = [
diff --git a/examples/codex-memory-plugin/scripts/shared/mcp-proxy-core.mjs b/examples/codex-memory-plugin/scripts/shared/mcp-proxy-core.mjs
index cb09673d6..4fc2483cb 100644
--- a/examples/codex-memory-plugin/scripts/shared/mcp-proxy-core.mjs
+++ b/examples/codex-memory-plugin/scripts/shared/mcp-proxy-core.mjs
@@ -142,6 +142,7 @@ export function createOpenVikingMcpProxy({
readConfig,
loggerFactory,
fetchImpl = globalThis.fetch,
+ localToolProvider = null,
} = {}) {
if (typeof fetchImpl !== "function") {
throw new Error("global fetch is required; use Node.js 18 or newer");
@@ -179,6 +180,43 @@ export function createOpenVikingMcpProxy({
} catch { /* debug logging must never affect protocol IO */ }
}
+ function localTools() {
+ if (!localToolProvider || typeof localToolProvider.listTools !== "function") return [];
+ const tools = localToolProvider.listTools();
+ return Array.isArray(tools) ? tools : [];
+ }
+
+ function appendLocalTools(message, outbound) {
+ if (message.method !== "tools/list" || !Array.isArray(outbound?.result?.tools)) {
+ return outbound;
+ }
+ const additions = localTools().filter((tool) => tool?.name);
+ if (additions.length === 0) return outbound;
+ const localNames = new Set(additions.map((tool) => tool.name));
+ const upstreamTools = outbound.result.tools.filter((tool) => !localNames.has(tool?.name));
+ return {
+ ...outbound,
+ result: {
+ ...outbound.result,
+ tools: [...upstreamTools, ...additions],
+ },
+ };
+ }
+
+ async function callLocalTool(message) {
+ if (
+ message.method !== "tools/call"
+ || !localToolProvider
+ || typeof localToolProvider.callTool !== "function"
+ ) {
+ return null;
+ }
+ const name = message.params?.name;
+ if (!localTools().some((tool) => tool?.name === name)) return null;
+ reloadIfCredentialFilesChanged("local_tool_call");
+ return localToolProvider.callTool(message.params, { config: proxyConfig });
+ }
+
function reloadConfig(reason) {
proxyConfig = readConfig();
logger = loggerFactory("mcp-proxy", proxyConfig);
@@ -381,6 +419,13 @@ export function createOpenVikingMcpProxy({
}
try {
+ const localResult = await callLocalTool(message);
+ if (localResult !== null) {
+ if (expectsResponse) {
+ await writeMessage({ jsonrpc: "2.0", id: message.id, result: localResult });
+ }
+ return;
+ }
const send = sendWithRetry(message, { expectsResponse });
if (message.method === "initialize") {
initializeInFlight = send
@@ -396,7 +441,7 @@ export function createOpenVikingMcpProxy({
return;
}
for (const outbound of result.messages) {
- await writeMessage(outbound);
+ await writeMessage(appendLocalTools(message, outbound));
}
} catch (err) {
if (expectsResponse) {
diff --git a/examples/codex-memory-plugin/servers/experience-tools.mjs b/examples/codex-memory-plugin/servers/experience-tools.mjs
new file mode 100644
index 000000000..5df915ce2
--- /dev/null
+++ b/examples/codex-memory-plugin/servers/experience-tools.mjs
@@ -0,0 +1,199 @@
+const EXPERIENCE_TARGET_URI = "viking://user/memories/experiences/";
+const DEFAULT_LIMIT = 5;
+const MAX_LIMIT = 20;
+const DEFAULT_TIMEOUT_MS = 15000;
+const EXPERIENCE_SIDECAR_FILENAMES = new Set([".abstract.md", ".overview.md", ".relations.json"]);
+
+const EXPERIENCE_TOOL_DEFINITIONS = [
+ {
+ name: "search_experience",
+ description: "Search reusable execution experiences for the current OpenViking user.",
+ inputSchema: {
+ type: "object",
+ properties: {
+ query: { type: "string", description: "Task or situation to search for." },
+ limit: {
+ type: "integer",
+ minimum: 1,
+ maximum: MAX_LIMIT,
+ default: DEFAULT_LIMIT,
+ },
+ },
+ required: ["query"],
+ additionalProperties: false,
+ },
+ },
+ {
+ name: "read_experience",
+ description: "Read one Experience returned by search_experience.",
+ inputSchema: {
+ type: "object",
+ properties: {
+ uri: {
+ type: "string",
+ description: "Canonical viking:// URI of an Experience memory file.",
+ },
+ },
+ required: ["uri"],
+ additionalProperties: false,
+ },
+ },
+];
+
+function result(payload) {
+ return {
+ content: [{ type: "text", text: JSON.stringify(payload) }],
+ };
+}
+
+function errorResult(message) {
+ return {
+ isError: true,
+ content: [{ type: "text", text: String(message) }],
+ };
+}
+
+function normalizedBaseUrl(config) {
+ const explicit = String(config?.baseUrl || "").trim().replace(/\/+$/, "");
+ if (explicit) return explicit;
+ const mcpUrl = new URL(String(config?.mcpUrl || ""));
+ mcpUrl.pathname = mcpUrl.pathname.replace(/\/mcp\/?$/, "").replace(/\/+$/, "");
+ mcpUrl.search = "";
+ mcpUrl.hash = "";
+ return mcpUrl.toString().replace(/\/+$/, "");
+}
+
+function requestHeaders(config, includeJson = false) {
+ const headers = { Accept: "application/json" };
+ if (includeJson) headers["Content-Type"] = "application/json";
+ if (config?.apiKey) headers.Authorization = `Bearer ${config.apiKey}`;
+ if (config?.account) headers["X-OpenViking-Account"] = config.account;
+ if (config?.user) headers["X-OpenViking-User"] = config.user;
+ if (config?.peerId) headers["X-OpenViking-Actor-Peer"] = config.peerId;
+ return headers;
+}
+
+function experiencePrefix(user) {
+ const owner = String(user || "").trim();
+ return owner ? `viking://user/${owner}/memories/experiences/` : "";
+}
+
+function isExperienceUri(uri, user) {
+ const value = String(uri || "").trim();
+ if (!value || value.includes("?") || value.includes("#")) return false;
+ const prefix = experiencePrefix(user);
+ const relative = prefix
+ ? (value.startsWith(prefix) ? value.slice(prefix.length) : "")
+ : value.match(/^viking:\/\/user\/[^/]+\/memories\/experiences\/(.+)$/)?.[1] || "";
+ const segments = relative.split("/");
+ const basename = segments.at(-1) || "";
+ return Boolean(
+ relative
+ && segments.length > 0
+ && segments.every((segment) => segment && segment !== "." && segment !== "..")
+ && !EXPERIENCE_SIDECAR_FILENAMES.has(basename),
+ );
+}
+
+function titleFromUri(uri) {
+ const basename = String(uri).split("/").at(-1) || String(uri);
+ const withoutExtension = basename.replace(/\.md$/i, "");
+ try {
+ return decodeURIComponent(withoutExtension);
+ } catch {
+ return withoutExtension;
+ }
+}
+
+function clampLimit(value) {
+ const parsed = Number.isFinite(Number(value)) ? Math.trunc(Number(value)) : DEFAULT_LIMIT;
+ return Math.max(1, Math.min(MAX_LIMIT, parsed));
+}
+
+function requestSignal(config) {
+ const configured = Number(config?.timeoutMs);
+ const timeoutMs = Math.max(1000, Number.isFinite(configured) ? configured : DEFAULT_TIMEOUT_MS);
+ return AbortSignal.timeout(timeoutMs);
+}
+
+async function readJsonResponse(response) {
+ const text = await response.text();
+ let payload;
+ try {
+ payload = text ? JSON.parse(text) : {};
+ } catch {
+ throw new Error(`OpenViking returned invalid JSON (HTTP ${response.status})`);
+ }
+ if (!response.ok) {
+ const detail = payload?.detail || payload?.message || payload?.error?.message || response.statusText;
+ throw new Error(`OpenViking request failed (HTTP ${response.status}): ${detail}`);
+ }
+ return payload;
+}
+
+async function searchExperience(args, config, fetchImpl) {
+ const query = String(args?.query || "").trim();
+ if (!query) return errorResult("search_experience requires a non-empty query");
+ try {
+ const response = await fetchImpl(`${normalizedBaseUrl(config)}/api/v1/search/find`, {
+ method: "POST",
+ headers: requestHeaders(config, true),
+ signal: requestSignal(config),
+ body: JSON.stringify({
+ query,
+ target_uri: EXPERIENCE_TARGET_URI,
+ limit: clampLimit(args?.limit),
+ }),
+ });
+ const payload = await readJsonResponse(response);
+ const memories = Array.isArray(payload?.result?.memories) ? payload.result.memories : [];
+ const results = memories
+ .filter((item) => isExperienceUri(item?.uri, config?.user))
+ .map((item) => ({
+ uri: item.uri,
+ title: titleFromUri(item.uri),
+ score: Number.isFinite(Number(item.score)) ? Number(item.score) : 0,
+ snippet: String(item.abstract || item.overview || ""),
+ }));
+ return result({ results });
+ } catch (error) {
+ return errorResult(error instanceof Error ? error.message : error);
+ }
+}
+
+async function readExperience(args, config, fetchImpl) {
+ const uri = String(args?.uri || "").trim();
+ if (!isExperienceUri(uri, config?.user)) {
+ return errorResult("read_experience requires an Experience URI owned by the current user");
+ }
+ try {
+ const url = `${normalizedBaseUrl(config)}/api/v1/content/read?uri=${encodeURIComponent(uri)}`;
+ const response = await fetchImpl(url, {
+ method: "GET",
+ headers: requestHeaders(config),
+ signal: requestSignal(config),
+ });
+ const payload = await readJsonResponse(response);
+ return result({ uri, content: String(payload?.result || "") });
+ } catch (error) {
+ return errorResult(error instanceof Error ? error.message : error);
+ }
+}
+
+export function createExperienceToolProvider({ fetchImpl = globalThis.fetch } = {}) {
+ if (typeof fetchImpl !== "function") throw new Error("fetchImpl must be a function");
+ return {
+ listTools() {
+ return EXPERIENCE_TOOL_DEFINITIONS.map((tool) => structuredClone(tool));
+ },
+ async callTool(params, { config } = {}) {
+ if (params?.name === "search_experience") {
+ return searchExperience(params.arguments, config, fetchImpl);
+ }
+ if (params?.name === "read_experience") {
+ return readExperience(params.arguments, config, fetchImpl);
+ }
+ return null;
+ },
+ };
+}
diff --git a/examples/codex-memory-plugin/servers/experience-tools.test.mjs b/examples/codex-memory-plugin/servers/experience-tools.test.mjs
new file mode 100644
index 000000000..24099d096
--- /dev/null
+++ b/examples/codex-memory-plugin/servers/experience-tools.test.mjs
@@ -0,0 +1,240 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+
+import { createExperienceToolProvider } from "./experience-tools.mjs";
+
+const config = {
+ baseUrl: "http://openviking.test",
+ apiKey: "test-key",
+ account: "new",
+ user: "test",
+ peerId: "peer-a",
+};
+
+function toolPayload(result) {
+ assert.equal(result.isError, undefined);
+ assert.equal(result.content.length, 1);
+ assert.equal(result.content[0].type, "text");
+ return JSON.parse(result.content[0].text);
+}
+
+test("lists the two official Experience tools", () => {
+ const provider = createExperienceToolProvider({ fetchImpl: async () => assert.fail("unexpected fetch") });
+ assert.deepEqual(
+ provider.listTools().map((tool) => tool.name),
+ ["search_experience", "read_experience"],
+ );
+});
+
+test("search_experience searches only the current user's Experience directory", async () => {
+ const calls = [];
+ const provider = createExperienceToolProvider({
+ fetchImpl: async (url, options) => {
+ calls.push({ url: String(url), options });
+ return new Response(JSON.stringify({
+ ok: true,
+ result: {
+ memories: [
+ {
+ uri: "viking://user/test/memories/experiences/无订单号换货处理.md",
+ score: 0.82,
+ abstract: "先验证身份,再逐个定位订单。",
+ },
+ {
+ uri: "viking://user/test/memories/preferences/回复风格.md",
+ score: 0.91,
+ abstract: "回复简洁。",
+ },
+ {
+ uri: "viking://user/test/memories/experiences/.abstract.md",
+ score: 0.95,
+ abstract: "Experience 目录摘要。",
+ },
+ {
+ uri: "viking://user/test/memories/experiences/.overview.md",
+ score: 0.94,
+ abstract: "Experience 目录概览。",
+ },
+ {
+ uri: "viking://user/test/memories/experiences/无订单号换货处理.md?source=codex",
+ score: 0.93,
+ abstract: "非规范 URI 别名。",
+ },
+ {
+ uri: "viking://user/test/memories/experiences/无订单号换货处理.md#approach",
+ score: 0.92,
+ abstract: "带片段的 URI 别名。",
+ },
+ ],
+ resources: [],
+ skills: [],
+ },
+ }), { status: 200, headers: { "content-type": "application/json" } });
+ },
+ });
+
+ const result = await provider.callTool(
+ { name: "search_experience", arguments: { query: "无订单号换货", limit: 5 } },
+ { config },
+ );
+
+ assert.equal(calls.length, 1);
+ assert.equal(calls[0].url, "http://openviking.test/api/v1/search/find");
+ assert.equal(calls[0].options.method, "POST");
+ assert.equal(calls[0].options.headers.Authorization, "Bearer test-key");
+ assert.equal(calls[0].options.headers["X-OpenViking-Account"], "new");
+ assert.equal(calls[0].options.headers["X-OpenViking-User"], "test");
+ assert.equal(calls[0].options.headers["X-OpenViking-Actor-Peer"], "peer-a");
+ assert.deepEqual(JSON.parse(calls[0].options.body), {
+ query: "无订单号换货",
+ target_uri: "viking://user/memories/experiences/",
+ limit: 5,
+ });
+ assert.deepEqual(toolPayload(result), {
+ results: [
+ {
+ uri: "viking://user/test/memories/experiences/无订单号换货处理.md",
+ title: "无订单号换货处理",
+ score: 0.82,
+ snippet: "先验证身份,再逐个定位订单。",
+ },
+ ],
+ });
+});
+
+test("read_experience reads a canonical Experience URI", async () => {
+ const calls = [];
+ const uri = "viking://user/test/memories/experiences/无订单号换货处理.md";
+ const provider = createExperienceToolProvider({
+ fetchImpl: async (url, options) => {
+ calls.push({ url: String(url), options });
+ return new Response(JSON.stringify({ ok: true, result: "## Approach\n先验证用户身份。" }), {
+ status: 200,
+ headers: { "content-type": "application/json" },
+ });
+ },
+ });
+
+ const result = await provider.callTool(
+ { name: "read_experience", arguments: { uri } },
+ { config },
+ );
+
+ assert.equal(calls.length, 1);
+ assert.equal(
+ calls[0].url,
+ `http://openviking.test/api/v1/content/read?uri=${encodeURIComponent(uri)}`,
+ );
+ assert.equal(calls[0].options.method, "GET");
+ assert.deepEqual(toolPayload(result), { uri, content: "## Approach\n先验证用户身份。" });
+});
+
+test("read_experience rejects non-Experience URIs without an HTTP request", async () => {
+ let callCount = 0;
+ const provider = createExperienceToolProvider({
+ fetchImpl: async () => {
+ callCount += 1;
+ return new Response();
+ },
+ });
+
+ const result = await provider.callTool(
+ {
+ name: "read_experience",
+ arguments: { uri: "viking://user/test/memories/preferences/回复风格.md" },
+ },
+ { config },
+ );
+
+ assert.equal(callCount, 0);
+ assert.equal(result.isError, true);
+ assert.match(result.content[0].text, /Experience URI/);
+});
+
+test("read_experience rejects noncanonical Experience URI aliases", async () => {
+ let callCount = 0;
+ const provider = createExperienceToolProvider({
+ fetchImpl: async () => {
+ callCount += 1;
+ return new Response();
+ },
+ });
+ const canonicalUri = "viking://user/test/memories/experiences/无订单号换货处理.md";
+
+ for (const uri of [`${canonicalUri}?source=codex`, `${canonicalUri}#approach`]) {
+ const result = await provider.callTool(
+ { name: "read_experience", arguments: { uri } },
+ { config },
+ );
+ assert.equal(result.isError, true);
+ }
+ assert.equal(callCount, 0);
+});
+
+test("read_experience rejects internal Experience sidecars", async () => {
+ let callCount = 0;
+ const provider = createExperienceToolProvider({
+ fetchImpl: async () => {
+ callCount += 1;
+ return new Response();
+ },
+ });
+
+ for (const name of [".abstract.md", ".overview.md", ".relations.json"]) {
+ const result = await provider.callTool(
+ {
+ name: "read_experience",
+ arguments: { uri: `viking://user/test/memories/experiences/${name}` },
+ },
+ { config },
+ );
+ assert.equal(result.isError, true);
+ }
+ assert.equal(callCount, 0);
+});
+
+test("read_experience accepts other dot-prefixed Experience files", async () => {
+ let callCount = 0;
+ const uri = "viking://user/test/memories/experiences/.custom-experience.md";
+ const provider = createExperienceToolProvider({
+ fetchImpl: async () => {
+ callCount += 1;
+ return new Response(JSON.stringify({ result: "content" }), { status: 200 });
+ },
+ });
+
+ const result = await provider.callTool(
+ { name: "read_experience", arguments: { uri } },
+ { config },
+ );
+
+ assert.equal(result.isError, undefined);
+ assert.equal(callCount, 1);
+});
+
+test("Experience HTTP requests inherit the configured timeout signal", async () => {
+ const calls = [];
+ const uri = "viking://user/test/memories/experiences/无订单号换货处理.md";
+ const provider = createExperienceToolProvider({
+ fetchImpl: async (url, options) => {
+ calls.push({ url: String(url), options });
+ if (String(url).includes("/search/find")) {
+ return new Response(JSON.stringify({ result: { memories: [] } }), { status: 200 });
+ }
+ return new Response(JSON.stringify({ result: "content" }), { status: 200 });
+ },
+ });
+ const timeoutConfig = { ...config, timeoutMs: 1234 };
+
+ await provider.callTool(
+ { name: "search_experience", arguments: { query: "换货" } },
+ { config: timeoutConfig },
+ );
+ await provider.callTool(
+ { name: "read_experience", arguments: { uri } },
+ { config: timeoutConfig },
+ );
+
+ assert.equal(calls.length, 2);
+ for (const call of calls) assert.ok(call.options.signal instanceof AbortSignal);
+});
diff --git a/examples/codex-memory-plugin/servers/mcp-proxy.mjs b/examples/codex-memory-plugin/servers/mcp-proxy.mjs
index f970d41b0..380b6ed5f 100644
--- a/examples/codex-memory-plugin/servers/mcp-proxy.mjs
+++ b/examples/codex-memory-plugin/servers/mcp-proxy.mjs
@@ -16,6 +16,7 @@ import { createLogger } from "../scripts/debug-log.mjs";
import { resolveOpenVikingCredentials } from "../scripts/ov-credentials.mjs";
import { createOpenVikingMcpProxy } from "../scripts/shared/mcp-proxy-core.mjs";
import { resolveEffectivePeerId } from "../scripts/shared/workspace-peer.mjs";
+import { createExperienceToolProvider } from "./experience-tools.mjs";
export { createOpenVikingMcpProxy } from "../scripts/shared/mcp-proxy-core.mjs";
@@ -43,6 +44,7 @@ function readProxyConfig() {
const effectivePeer = resolveEffectivePeerId({ cfg, cwd: process.cwd() });
const mcpUrl = creds.mcpUrl || `${trimSlash(creds.baseUrl)}/mcp`;
return {
+ baseUrl: trimSlash(creds.baseUrl),
mcpUrl,
apiKey: creds.apiKey || "",
account: creds.account || "",
@@ -66,5 +68,10 @@ function readProxyConfig() {
}
if (process.argv[1] && fileURLToPath(import.meta.url) === resolvePath(process.argv[1])) {
- createOpenVikingMcpProxy({ readConfig: readProxyConfig, loggerFactory: createLogger }).start();
+ const localToolProvider = createExperienceToolProvider();
+ createOpenVikingMcpProxy({
+ readConfig: readProxyConfig,
+ loggerFactory: createLogger,
+ localToolProvider,
+ }).start();
}
diff --git a/examples/codex-memory-plugin/servers/mcp-proxy.test.mjs b/examples/codex-memory-plugin/servers/mcp-proxy.test.mjs
index b5cd6d4cd..995d36d1b 100644
--- a/examples/codex-memory-plugin/servers/mcp-proxy.test.mjs
+++ b/examples/codex-memory-plugin/servers/mcp-proxy.test.mjs
@@ -1,5 +1,8 @@
import assert from "node:assert/strict";
+import { mkdtempSync, rmSync, writeFileSync } from "node:fs";
import { createServer } from "node:http";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
import { Writable } from "node:stream";
import test from "node:test";
import { createOpenVikingMcpProxy } from "./mcp-proxy.mjs";
@@ -39,7 +42,7 @@ async function withServer(handler, fn) {
}
}
-function makeProxy({ url, configOverrides = {}, stdout } = {}) {
+function makeProxy({ url, configOverrides = {}, stdout, localToolProvider, readConfig } = {}) {
const out = [];
const writable = stdout || new Writable({
write(chunk, _encoding, callback) {
@@ -49,7 +52,7 @@ function makeProxy({ url, configOverrides = {}, stdout } = {}) {
});
const proxy = createOpenVikingMcpProxy({
stdout: writable,
- readConfig: () => ({
+ readConfig: readConfig || (() => ({
mcpUrl: url,
apiKey: "test-key",
account: "default",
@@ -62,8 +65,9 @@ function makeProxy({ url, configOverrides = {}, stdout } = {}) {
credentialPath: "",
watchedPaths: [],
...configOverrides,
- }),
+ })),
loggerFactory: () => ({ log() {}, logError() {} }),
+ localToolProvider,
});
return {
proxy,
@@ -191,6 +195,152 @@ test("uses independent POST requests for concurrent calls", async () => {
});
});
+test("appends local tools to the upstream tools/list result", async () => {
+ const localTools = [
+ { name: "search_experience", description: "Search experiences", inputSchema: { type: "object" } },
+ { name: "read_experience", description: "Read an experience", inputSchema: { type: "object" } },
+ ];
+ await withServer((_req, res, entry) => {
+ assert.equal(entry.body.method, "tools/list");
+ res.writeHead(200, { "content-type": "application/json" });
+ res.end(JSON.stringify(jsonRpc(entry.body.id, {
+ tools: [{ name: "find", description: "Find context", inputSchema: { type: "object" } }],
+ })));
+ }, async ({ url, requests }) => {
+ const { proxy, messages } = makeProxy({
+ url,
+ localToolProvider: {
+ listTools: () => localTools,
+ async callTool() { return null; },
+ },
+ });
+
+ await proxy.handleMessage({ jsonrpc: "2.0", id: 20, method: "tools/list" });
+
+ const [response] = await messages();
+ assert.deepEqual(response.result.tools.map((tool) => tool.name), [
+ "find",
+ "search_experience",
+ "read_experience",
+ ]);
+ assert.equal(requests.length, 1);
+ });
+});
+
+test("replaces an upstream tool definition when the local tool has the same name", async () => {
+ const localTool = {
+ name: "search_experience",
+ description: "Local experience search",
+ inputSchema: { type: "object", required: ["query"] },
+ };
+ await withServer((_req, res, entry) => {
+ assert.equal(entry.body.method, "tools/list");
+ res.writeHead(200, { "content-type": "application/json" });
+ res.end(JSON.stringify(jsonRpc(entry.body.id, {
+ tools: [
+ { name: "find", description: "Find context", inputSchema: { type: "object" } },
+ {
+ name: "search_experience",
+ description: "Upstream experience search",
+ inputSchema: { type: "object", required: ["text"] },
+ },
+ ],
+ })));
+ }, async ({ url }) => {
+ const { proxy, messages } = makeProxy({
+ url,
+ localToolProvider: {
+ listTools: () => [localTool],
+ async callTool() { return null; },
+ },
+ });
+
+ await proxy.handleMessage({ jsonrpc: "2.0", id: 22, method: "tools/list" });
+
+ const [response] = await messages();
+ assert.deepEqual(response.result.tools, [
+ { name: "find", description: "Find context", inputSchema: { type: "object" } },
+ localTool,
+ ]);
+ });
+});
+
+test("handles local tools without forwarding tools/call upstream", async () => {
+ const calls = [];
+ const { proxy, messages } = makeProxy({
+ url: "http://127.0.0.1:1/mcp",
+ localToolProvider: {
+ listTools: () => [{ name: "search_experience" }],
+ async callTool(params, context) {
+ calls.push({ params, context });
+ return { content: [{ type: "text", text: '{"results":[]}' }] };
+ },
+ },
+ });
+
+ await proxy.handleMessage({
+ jsonrpc: "2.0",
+ id: 21,
+ method: "tools/call",
+ params: { name: "search_experience", arguments: { query: "换货" } },
+ });
+
+ assert.equal(calls.length, 1);
+ assert.deepEqual(calls[0].params, {
+ name: "search_experience",
+ arguments: { query: "换货" },
+ });
+ assert.equal(calls[0].context.config.user, "zeus");
+ assert.deepEqual(await messages(), [
+ jsonRpc(21, { content: [{ type: "text", text: '{"results":[]}' }] }),
+ ]);
+});
+
+test("reloads changed credential files before calling a local tool", async (t) => {
+ const dir = mkdtempSync(join(tmpdir(), "openviking-mcp-proxy-"));
+ const credentialPath = join(dir, "ovcli.conf");
+ writeFileSync(credentialPath, "old-key", "utf-8");
+ t.after(() => rmSync(dir, { recursive: true, force: true }));
+
+ let apiKey = "old-key";
+ const receivedKeys = [];
+ const readConfig = () => ({
+ mcpUrl: "http://127.0.0.1:1/mcp",
+ apiKey,
+ account: "default",
+ user: "zeus",
+ peerId: "peer-a",
+ timeoutMs: 5000,
+ debug: false,
+ debugLogPath: "",
+ credentialSource: "ovcli",
+ credentialPath,
+ watchedPaths: [credentialPath],
+ });
+ const { proxy, messages } = makeProxy({
+ readConfig,
+ localToolProvider: {
+ listTools: () => [{ name: "search_experience" }],
+ async callTool(_params, context) {
+ receivedKeys.push(context.config.apiKey);
+ return { content: [{ type: "text", text: '{"results":[]}' }] };
+ },
+ },
+ });
+
+ apiKey = "new-key";
+ writeFileSync(credentialPath, "new-key-with-different-size", "utf-8");
+ await proxy.handleMessage({
+ jsonrpc: "2.0",
+ id: 22,
+ method: "tools/call",
+ params: { name: "search_experience", arguments: { query: "换货" } },
+ });
+
+ assert.deepEqual(receivedKeys, ["new-key"]);
+ assert.equal((await messages())[0].id, 22);
+});
+
test("reinitializes after 404 and retries the original request once", async () => {
let call = 0;
await withServer((_req, res, entry) => {
diff --git a/examples/codex-memory-plugin/skills/ov-experience-memory/SKILL.md b/examples/codex-memory-plugin/skills/ov-experience-memory/SKILL.md
new file mode 100644
index 000000000..1faa749e2
--- /dev/null
+++ b/examples/codex-memory-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/memory-plugin-shared/lib/mcp-proxy-core.mjs b/examples/memory-plugin-shared/lib/mcp-proxy-core.mjs
index be7f3c760..f87a908d8 100644
--- a/examples/memory-plugin-shared/lib/mcp-proxy-core.mjs
+++ b/examples/memory-plugin-shared/lib/mcp-proxy-core.mjs
@@ -141,6 +141,7 @@ export function createOpenVikingMcpProxy({
readConfig,
loggerFactory,
fetchImpl = globalThis.fetch,
+ localToolProvider = null,
} = {}) {
if (typeof fetchImpl !== "function") {
throw new Error("global fetch is required; use Node.js 18 or newer");
@@ -178,6 +179,43 @@ export function createOpenVikingMcpProxy({
} catch { /* debug logging must never affect protocol IO */ }
}
+ function localTools() {
+ if (!localToolProvider || typeof localToolProvider.listTools !== "function") return [];
+ const tools = localToolProvider.listTools();
+ return Array.isArray(tools) ? tools : [];
+ }
+
+ function appendLocalTools(message, outbound) {
+ if (message.method !== "tools/list" || !Array.isArray(outbound?.result?.tools)) {
+ return outbound;
+ }
+ const additions = localTools().filter((tool) => tool?.name);
+ if (additions.length === 0) return outbound;
+ const localNames = new Set(additions.map((tool) => tool.name));
+ const upstreamTools = outbound.result.tools.filter((tool) => !localNames.has(tool?.name));
+ return {
+ ...outbound,
+ result: {
+ ...outbound.result,
+ tools: [...upstreamTools, ...additions],
+ },
+ };
+ }
+
+ async function callLocalTool(message) {
+ if (
+ message.method !== "tools/call"
+ || !localToolProvider
+ || typeof localToolProvider.callTool !== "function"
+ ) {
+ return null;
+ }
+ const name = message.params?.name;
+ if (!localTools().some((tool) => tool?.name === name)) return null;
+ reloadIfCredentialFilesChanged("local_tool_call");
+ return localToolProvider.callTool(message.params, { config: proxyConfig });
+ }
+
function reloadConfig(reason) {
proxyConfig = readConfig();
logger = loggerFactory("mcp-proxy", proxyConfig);
@@ -380,6 +418,13 @@ export function createOpenVikingMcpProxy({
}
try {
+ const localResult = await callLocalTool(message);
+ if (localResult !== null) {
+ if (expectsResponse) {
+ await writeMessage({ jsonrpc: "2.0", id: message.id, result: localResult });
+ }
+ return;
+ }
const send = sendWithRetry(message, { expectsResponse });
if (message.method === "initialize") {
initializeInFlight = send
@@ -395,7 +440,7 @@ export function createOpenVikingMcpProxy({
return;
}
for (const outbound of result.messages) {
- await writeMessage(outbound);
+ await writeMessage(appendLocalTools(message, outbound));
}
} catch (err) {
if (expectsResponse) {
diff --git a/examples/opencode-plugin/lib/shared/mcp-proxy-core.mjs b/examples/opencode-plugin/lib/shared/mcp-proxy-core.mjs
index cb09673d6..4fc2483cb 100644
--- a/examples/opencode-plugin/lib/shared/mcp-proxy-core.mjs
+++ b/examples/opencode-plugin/lib/shared/mcp-proxy-core.mjs
@@ -142,6 +142,7 @@ export function createOpenVikingMcpProxy({
readConfig,
loggerFactory,
fetchImpl = globalThis.fetch,
+ localToolProvider = null,
} = {}) {
if (typeof fetchImpl !== "function") {
throw new Error("global fetch is required; use Node.js 18 or newer");
@@ -179,6 +180,43 @@ export function createOpenVikingMcpProxy({
} catch { /* debug logging must never affect protocol IO */ }
}
+ function localTools() {
+ if (!localToolProvider || typeof localToolProvider.listTools !== "function") return [];
+ const tools = localToolProvider.listTools();
+ return Array.isArray(tools) ? tools : [];
+ }
+
+ function appendLocalTools(message, outbound) {
+ if (message.method !== "tools/list" || !Array.isArray(outbound?.result?.tools)) {
+ return outbound;
+ }
+ const additions = localTools().filter((tool) => tool?.name);
+ if (additions.length === 0) return outbound;
+ const localNames = new Set(additions.map((tool) => tool.name));
+ const upstreamTools = outbound.result.tools.filter((tool) => !localNames.has(tool?.name));
+ return {
+ ...outbound,
+ result: {
+ ...outbound.result,
+ tools: [...upstreamTools, ...additions],
+ },
+ };
+ }
+
+ async function callLocalTool(message) {
+ if (
+ message.method !== "tools/call"
+ || !localToolProvider
+ || typeof localToolProvider.callTool !== "function"
+ ) {
+ return null;
+ }
+ const name = message.params?.name;
+ if (!localTools().some((tool) => tool?.name === name)) return null;
+ reloadIfCredentialFilesChanged("local_tool_call");
+ return localToolProvider.callTool(message.params, { config: proxyConfig });
+ }
+
function reloadConfig(reason) {
proxyConfig = readConfig();
logger = loggerFactory("mcp-proxy", proxyConfig);
@@ -381,6 +419,13 @@ export function createOpenVikingMcpProxy({
}
try {
+ const localResult = await callLocalTool(message);
+ if (localResult !== null) {
+ if (expectsResponse) {
+ await writeMessage({ jsonrpc: "2.0", id: message.id, result: localResult });
+ }
+ return;
+ }
const send = sendWithRetry(message, { expectsResponse });
if (message.method === "initialize") {
initializeInFlight = send
@@ -396,7 +441,7 @@ export function createOpenVikingMcpProxy({
return;
}
for (const outbound of result.messages) {
- await writeMessage(outbound);
+ await writeMessage(appendLocalTools(message, outbound));
}
} catch (err) {
if (expectsResponse) {
diff --git a/examples/skills/ov-experience-memory/SKILL.md b/examples/skills/ov-experience-memory/SKILL.md
new file mode 100644
index 000000000..1faa749e2
--- /dev/null
+++ b/examples/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/openviking/server/app.py b/openviking/server/app.py
index c50e500a9..607befe0a 100644
--- a/openviking/server/app.py
+++ b/openviking/server/app.py
@@ -202,14 +202,29 @@ def create_app(
validate_server_config(config)
- def _configure_session_tool_outputs(service_obj) -> None: # noqa: ANN001
+ usage_reporter_unset = object()
+ usage_reporter = usage_reporter_unset
+
+ def _get_usage_reporter(): # noqa: ANN202
+ nonlocal usage_reporter
+ if usage_reporter is usage_reporter_unset:
+ from openviking.usage_reporter.config import build_usage_reporter
+
+ usage_reporter = build_usage_reporter(config.usage_reporter)
+ return usage_reporter
+
+ def _configure_session_runtime(service_obj) -> None: # noqa: ANN001
sessions = getattr(service_obj, "sessions", None)
- setter = getattr(sessions, "set_tool_output_externalization_config", None)
- if callable(setter):
- setter(config.tool_output_externalization)
+ tool_output_setter = getattr(sessions, "set_tool_output_externalization_config", None)
+ if callable(tool_output_setter):
+ tool_output_setter(config.tool_output_externalization)
+
+ usage_reporter_setter = getattr(sessions, "set_usage_reporter", None)
+ if callable(usage_reporter_setter):
+ usage_reporter_setter(_get_usage_reporter())
if service is not None:
- _configure_session_tool_outputs(service)
+ _configure_session_runtime(service)
@asynccontextmanager
async def lifespan(app: FastAPI):
@@ -220,7 +235,7 @@ def create_app(
service = OpenVikingService()
assert service is not None
- _configure_session_tool_outputs(service)
+ _configure_session_runtime(service)
set_service(service)
from openviking.metrics.global_api import (
@@ -301,6 +316,8 @@ def create_app(
logger.warning(f"OpenVikingService close cancelled during shutdown: {e}")
except Exception as e:
logger.warning(f"OpenVikingService close failed during shutdown: {e}")
+ if usage_reporter is not usage_reporter_unset and usage_reporter is not None:
+ await usage_reporter.close()
app = FastAPI(
title="OpenViking API",
diff --git a/openviking/server/config.py b/openviking/server/config.py
index f208695ee..d158eb2d6 100644
--- a/openviking/server/config.py
+++ b/openviking/server/config.py
@@ -173,6 +173,26 @@ class UsageAuditConfig(BaseModel):
model_config = {"extra": "forbid"}
+class UsageReporterSinkConfig(BaseModel):
+ """Usage reporter sink configuration."""
+
+ type: Literal["custom"] = "custom"
+ class_path: Optional[str] = None
+ config: Dict[str, object] = Field(default_factory=dict)
+
+ model_config = {"extra": "forbid"}
+
+
+class UsageReporterConfig(BaseModel):
+ """Usage event reporter configuration."""
+
+ enabled: bool = False
+ extractors: List[Literal["memory_usage"]] = Field(default_factory=lambda: ["memory_usage"])
+ sinks: List[UsageReporterSinkConfig] = Field(default_factory=list)
+
+ model_config = {"extra": "forbid"}
+
+
class TraceDumpBodyConfig(BaseModel):
"""HTTP body dump configuration.
@@ -237,6 +257,7 @@ class ServerConfig(BaseModel):
encryption_enabled: bool = False # Whether file-level AES encryption is enabled
api_key_hashing_enabled: bool = False # Whether API key Argon2id hashing is enabled (default: false, rely on file encryption)
observability: ObservabilityConfig = Field(default_factory=ObservabilityConfig)
+ usage_reporter: UsageReporterConfig = Field(default_factory=UsageReporterConfig)
# Public-facing base URL emitted in MCP-issued upload instructions. See
# ``openviking.server.mcp_endpoint._resolve_public_base_url`` for the full
# resolution chain: env var > this field > X-Forwarded-Host/Proto > Host header
diff --git a/openviking/service/session_service.py b/openviking/service/session_service.py
index d3e5eb1a7..867ecaf48 100644
--- a/openviking/service/session_service.py
+++ b/openviking/service/session_service.py
@@ -28,6 +28,7 @@ logger = get_logger(__name__)
if TYPE_CHECKING:
from openviking.session.compressor_v2 import SessionCompressorV2
+ from openviking.usage_reporter import UsageReporter
class SessionService:
@@ -43,6 +44,7 @@ class SessionService:
self._viking_fs = viking_fs
self._session_compressor = session_compressor
self._tool_output_externalization_config = ToolOutputExternalizationConfig()
+ self._usage_reporter: Optional["UsageReporter"] = None
def set_dependencies(
self,
@@ -61,6 +63,10 @@ class SessionService:
"""Set tool output externalization controls for newly created sessions."""
self._tool_output_externalization_config = config.model_copy(deep=True)
+ def set_usage_reporter(self, usage_reporter: Optional["UsageReporter"]) -> None:
+ """Set the usage reporter for newly created sessions."""
+ self._usage_reporter = usage_reporter
+
def _ensure_initialized(self) -> None:
"""Ensure all dependencies are initialized."""
if not self._viking_fs:
@@ -120,6 +126,7 @@ class SessionService:
session_id=session_id,
session_uri=session_uri,
tool_output_externalization_config=self._tool_output_externalization_config,
+ usage_reporter=self._usage_reporter,
)
async def create(
diff --git a/openviking/session/session.py b/openviking/session/session.py
index d5450527c..4eaca02c1 100644
--- a/openviking/session/session.py
+++ b/openviking/session/session.py
@@ -47,6 +47,7 @@ if TYPE_CHECKING:
from openviking.storage import VikingDBManager
from openviking.storage.queuefs.session_commit_msg import SessionCommitMsg
from openviking.storage.viking_fs import VikingFS
+ from openviking.usage_reporter import UsageReporter
logger = get_logger(__name__)
@@ -362,6 +363,7 @@ class Session:
session_uri: Optional[str] = None,
auto_commit_threshold: int = 8000,
tool_output_externalization_config: Optional[ToolOutputExternalizationConfig] = None,
+ usage_reporter: Optional["UsageReporter"] = None,
):
self._viking_fs = viking_fs
self._vikingdb_manager = vikingdb_manager
@@ -391,6 +393,7 @@ class Session:
if tool_output_externalization_config is not None
else ToolOutputExternalizationConfig()
)
+ self._usage_reporter = usage_reporter
logger.info(f"Session created: {self.session_id} for user {self.user}")
@@ -1299,6 +1302,28 @@ class Session:
memory_policy=msg.memory_policy,
)
+ async def _run_usage_reporting(
+ self,
+ *,
+ task_id: str,
+ archive_uri: str,
+ messages: List[Message],
+ ) -> list[Any]:
+ reporter = getattr(self, "_usage_reporter", None)
+ if reporter is None:
+ return []
+
+ from openviking.usage_reporter import UsageContext
+
+ context = UsageContext(
+ account_id=self.ctx.account_id,
+ user_id=self.ctx.user.user_id,
+ session_id=self.session_id,
+ archive_uri=archive_uri,
+ task_id=task_id,
+ )
+ return await reporter.extract_and_report(messages=messages, context=context)
+
@tracer("session.commit.phase2", ignore_result=True, ignore_args=True)
async def _run_memory_extraction(
self,
@@ -1319,6 +1344,7 @@ class Session:
request_wait_tracker = get_request_wait_tracker()
memories_extracted: Dict[str, int] = {}
+ usage_events_extracted = 0
extracted_skill_results: list[dict] = []
active_count_updated = 0
memory_diff_uri: Optional[str] = None
@@ -1348,6 +1374,13 @@ class Session:
else ""
)
extraction_messages = await self._hydrate_tool_outputs_for_extraction(messages)
+ usage_events_extracted = len(
+ await self._run_usage_reporting(
+ task_id=task_id,
+ archive_uri=archive_uri,
+ messages=extraction_messages,
+ )
+ )
async def _run_archive_summary() -> None:
if not working_memory_enabled:
@@ -1646,6 +1679,7 @@ class Session:
for item in extracted_skill_results
if isinstance(item, dict) and (item.get("uri") or item.get("root_uri"))
],
+ "usage_events_extracted": usage_events_extracted,
"active_count_updated": active_count_updated,
"token_usage": {
"llm": dict(self._meta.llm_token_usage),
diff --git a/openviking/usage_reporter/__init__.py b/openviking/usage_reporter/__init__.py
new file mode 100644
index 000000000..7382cbbb4
--- /dev/null
+++ b/openviking/usage_reporter/__init__.py
@@ -0,0 +1,17 @@
+# Copyright (c) 2026 Beijing Volcano Engine Technology Co., Ltd.
+# SPDX-License-Identifier: AGPL-3.0
+"""Usage reporting extension points for OpenViking."""
+
+from .extractors import MemoryUsageExtractor, UsageExtractor
+from .models import UsageContext, UsageEvent
+from .reporter import UsageReporter
+from .sinks import UsageSink
+
+__all__ = [
+ "MemoryUsageExtractor",
+ "UsageContext",
+ "UsageEvent",
+ "UsageExtractor",
+ "UsageReporter",
+ "UsageSink",
+]
diff --git a/openviking/usage_reporter/config.py b/openviking/usage_reporter/config.py
new file mode 100644
index 000000000..f1ea78cdc
--- /dev/null
+++ b/openviking/usage_reporter/config.py
@@ -0,0 +1,52 @@
+# Copyright (c) 2026 Beijing Volcano Engine Technology Co., Ltd.
+# SPDX-License-Identifier: AGPL-3.0
+"""Build usage reporter instances from server config."""
+
+from __future__ import annotations
+
+import importlib
+from typing import Any
+
+from openviking.server.config import UsageReporterConfig, UsageReporterSinkConfig
+
+from .extractors import MemoryUsageExtractor
+from .reporter import UsageReporter
+from .sinks import UsageSink
+
+
+def _load_class(class_path: str) -> type:
+ module_name, class_name = class_path.rsplit(".", 1)
+ module = importlib.import_module(module_name)
+ cls = getattr(module, class_name)
+ if not isinstance(cls, type):
+ raise TypeError(f"{class_path} does not resolve to a class")
+ return cls
+
+
+def _build_sink(config: UsageReporterSinkConfig) -> UsageSink:
+ if config.type == "custom":
+ if not config.class_path:
+ raise ValueError("custom usage sink requires class_path")
+ cls = _load_class(config.class_path)
+ kwargs: dict[str, Any] = dict(config.config)
+ return cls(**kwargs)
+
+ raise ValueError(f"Unsupported usage sink type: {config.type}")
+
+
+def build_usage_reporter(config: UsageReporterConfig) -> UsageReporter | None:
+ if not config.enabled:
+ return None
+
+ extractors = []
+ for name in config.extractors:
+ if name == "memory_usage":
+ extractors.append(MemoryUsageExtractor())
+ else:
+ raise ValueError(f"Unsupported usage extractor: {name}")
+
+ sinks = [_build_sink(sink_config) for sink_config in config.sinks]
+ return UsageReporter(
+ extractors=extractors,
+ sinks=sinks,
+ )
diff --git a/openviking/usage_reporter/extractors.py b/openviking/usage_reporter/extractors.py
new file mode 100644
index 000000000..daf970707
--- /dev/null
+++ b/openviking/usage_reporter/extractors.py
@@ -0,0 +1,192 @@
+# Copyright (c) 2026 Beijing Volcano Engine Technology Co., Ltd.
+# SPDX-License-Identifier: AGPL-3.0
+"""Usage event extractors."""
+
+from __future__ import annotations
+
+import json
+from datetime import datetime
+from typing import Any, Iterable, Protocol
+
+from openviking.message import Message, ToolPart
+from openviking.utils.time_utils import format_iso8601, parse_iso_datetime
+
+from .models import UsageContext, UsageEvent, utc_now_iso
+
+_EXPERIENCE_SIDECAR_FILENAMES = {".abstract.md", ".overview.md", ".relations.json"}
+
+
+class UsageExtractor(Protocol):
+ name: str
+
+ async def extract(
+ self,
+ *,
+ messages: list[Message],
+ context: UsageContext,
+ ) -> list[UsageEvent]: ...
+
+
+def _load_mapping(value: Any) -> dict[str, Any]:
+ if isinstance(value, dict):
+ return value
+ if isinstance(value, str) and value.strip():
+ try:
+ parsed = json.loads(value)
+ except json.JSONDecodeError:
+ return {}
+ return parsed if isinstance(parsed, dict) else {}
+ return {}
+
+
+def _is_experience_uri(uri: str, context: UsageContext) -> bool:
+ prefix = f"viking://user/{context.user_id}/memories/experiences/"
+ if not uri.startswith(prefix) or "?" in uri or "#" in uri:
+ return False
+ relative = uri.removeprefix(prefix)
+ segments = relative.split("/")
+ if not relative or any(not segment or segment in {".", ".."} for segment in segments):
+ return False
+ return segments[-1] not in _EXPERIENCE_SIDECAR_FILENAMES
+
+
+def _event_time(message: Message) -> str:
+ value = message.created_at
+ try:
+ if isinstance(value, datetime):
+ return format_iso8601(value)
+ if isinstance(value, str) and value.strip():
+ return format_iso8601(parse_iso_datetime(value.strip()))
+ except (TypeError, ValueError):
+ pass
+ return utc_now_iso()
+
+
+class MemoryUsageExtractor:
+ """Extract memory recalled/injected usage events from official tool parts."""
+
+ name = "memory_usage"
+
+ async def extract(
+ self,
+ *,
+ messages: list[Message],
+ context: UsageContext,
+ ) -> list[UsageEvent]:
+ events: list[UsageEvent] = []
+ tool_inputs: dict[tuple[str, str], dict[str, Any]] = {}
+ for message in messages:
+ for part in message.parts:
+ if (
+ isinstance(part, ToolPart)
+ and part.tool_id
+ and isinstance(part.tool_input, dict)
+ and part.tool_input
+ ):
+ tool_inputs[(part.tool_id, part.tool_name)] = part.tool_input
+
+ for message in messages:
+ for part in message.parts:
+ if not isinstance(part, ToolPart):
+ continue
+ if not part.tool_id:
+ continue
+ if part.tool_status != "completed":
+ continue
+ if part.tool_name == "search_experience":
+ events.extend(
+ self._extract_search_events(
+ part,
+ context=context,
+ message=message,
+ )
+ )
+ elif part.tool_name == "read_experience":
+ event = self._extract_read_event(
+ part,
+ context=context,
+ message=message,
+ fallback_input=tool_inputs.get((part.tool_id, part.tool_name), {}),
+ )
+ if event is not None:
+ events.append(event)
+ return events
+
+ def _extract_search_events(
+ self,
+ part: ToolPart,
+ *,
+ context: UsageContext,
+ message: Message,
+ ) -> Iterable[UsageEvent]:
+ output = _load_mapping(part.tool_output)
+ results = output.get("results", [])
+ if not isinstance(results, list):
+ return []
+
+ events: list[UsageEvent] = []
+ for result in results:
+ if not isinstance(result, dict):
+ continue
+ uri = str(result.get("uri") or "").strip()
+ if not uri or not _is_experience_uri(uri, context):
+ continue
+ events.append(
+ self._build_event(
+ event_type="memory.recalled",
+ resource_uri=uri,
+ part=part,
+ context=context,
+ message=message,
+ )
+ )
+ return events
+
+ def _extract_read_event(
+ self,
+ part: ToolPart,
+ *,
+ context: UsageContext,
+ message: Message,
+ fallback_input: dict[str, Any],
+ ) -> UsageEvent | None:
+ tool_input = part.tool_input if isinstance(part.tool_input, dict) else {}
+ if not tool_input:
+ tool_input = fallback_input
+ output = _load_mapping(part.tool_output)
+ uri = str(tool_input.get("uri") or output.get("uri") or "").strip()
+ if not uri or not _is_experience_uri(uri, context):
+ return None
+ return self._build_event(
+ event_type="memory.injected",
+ resource_uri=uri,
+ part=part,
+ context=context,
+ message=message,
+ )
+
+ def _build_event(
+ self,
+ *,
+ event_type: str,
+ resource_uri: str,
+ part: ToolPart,
+ context: UsageContext,
+ message: Message,
+ ) -> UsageEvent:
+ return UsageEvent(
+ event_type=event_type,
+ resource_uri=resource_uri,
+ resource_type="experience",
+ account_id=context.account_id,
+ user_id=context.user_id,
+ session_id=context.session_id,
+ task_id=context.task_id,
+ occurred_at=_event_time(message),
+ evidence={
+ "archive_uri": context.archive_uri,
+ "message_id": message.id,
+ "tool_call_id": part.tool_id,
+ "tool_name": part.tool_name,
+ },
+ )
diff --git a/openviking/usage_reporter/models.py b/openviking/usage_reporter/models.py
new file mode 100644
index 000000000..c82105740
--- /dev/null
+++ b/openviking/usage_reporter/models.py
@@ -0,0 +1,61 @@
+# Copyright (c) 2026 Beijing Volcano Engine Technology Co., Ltd.
+# SPDX-License-Identifier: AGPL-3.0
+"""Usage reporter data models."""
+
+from __future__ import annotations
+
+import hashlib
+import json
+from dataclasses import asdict, dataclass, field
+from datetime import datetime, timezone
+from typing import Any, Dict, Optional
+
+
+def utc_now_iso() -> str:
+ return datetime.now(timezone.utc).isoformat(timespec="milliseconds").replace("+00:00", "Z")
+
+
+@dataclass(frozen=True)
+class UsageContext:
+ account_id: str
+ user_id: str
+ session_id: str
+ archive_uri: str
+ task_id: Optional[str] = None
+
+
+@dataclass(frozen=True)
+class UsageEvent:
+ event_type: str
+ resource_uri: str
+ resource_type: str
+ account_id: str
+ user_id: str
+ session_id: str
+ occurred_at: str
+ schema_version: str = "v1"
+ task_id: Optional[str] = None
+ evidence: Dict[str, Any] = field(default_factory=dict)
+ attributes: Dict[str, Any] = field(default_factory=dict)
+ event_id: str = ""
+
+ def __post_init__(self) -> None:
+ if self.event_id:
+ return
+ identity = [
+ self.schema_version,
+ self.event_type,
+ self.account_id,
+ self.user_id,
+ self.session_id,
+ self.task_id or "",
+ str(self.evidence.get("archive_uri") or ""),
+ str(self.evidence.get("tool_call_id") or ""),
+ self.resource_uri,
+ ]
+ encoded = json.dumps(identity, ensure_ascii=False, separators=(",", ":")).encode("utf-8")
+ digest = hashlib.sha256(encoded).hexdigest()
+ object.__setattr__(self, "event_id", f"ue_{digest}")
+
+ def to_dict(self) -> Dict[str, Any]:
+ return asdict(self)
diff --git a/openviking/usage_reporter/reporter.py b/openviking/usage_reporter/reporter.py
new file mode 100644
index 000000000..a93f0aab9
--- /dev/null
+++ b/openviking/usage_reporter/reporter.py
@@ -0,0 +1,119 @@
+# Copyright (c) 2026 Beijing Volcano Engine Technology Co., Ltd.
+# SPDX-License-Identifier: AGPL-3.0
+"""Usage reporter dispatcher."""
+
+from __future__ import annotations
+
+import asyncio
+import concurrent.futures
+import inspect
+import threading
+from dataclasses import dataclass, field
+from typing import Iterable
+
+from openviking_cli.utils import get_logger
+
+from .extractors import UsageExtractor
+from .models import UsageContext, UsageEvent
+from .sinks import UsageSink
+
+logger = get_logger(__name__)
+
+
+@dataclass
+class UsageReporter:
+ extractors: list[UsageExtractor] = field(default_factory=list)
+ sinks: list[UsageSink] = field(default_factory=list)
+ sink_timeout_seconds: float = 5.0
+
+ async def extract(
+ self,
+ *,
+ messages,
+ context: UsageContext,
+ ) -> list[UsageEvent]:
+ events: list[UsageEvent] = []
+ for extractor in self.extractors:
+ try:
+ events.extend(await extractor.extract(messages=messages, context=context))
+ except Exception:
+ logger.exception("Usage extractor failed: %s", getattr(extractor, "name", ""))
+ return events
+
+ async def report(
+ self,
+ *,
+ events: Iterable[UsageEvent],
+ ) -> None:
+ event_list = list(events)
+ if not event_list or not self.sinks:
+ return
+ await asyncio.gather(
+ *(self._report_to_sink(sink=sink, events=event_list) for sink in self.sinks)
+ )
+
+ async def _report_to_sink(self, *, sink: UsageSink, events: list[UsageEvent]) -> None:
+ try:
+ await asyncio.wait_for(
+ sink.write(events=events),
+ timeout=self.sink_timeout_seconds,
+ )
+ except TimeoutError:
+ logger.warning(
+ "Usage sink timed out after %.1fs: %s",
+ self.sink_timeout_seconds,
+ type(sink).__name__,
+ )
+ except Exception:
+ logger.exception("Usage sink failed: %s", type(sink).__name__)
+
+ async def extract_and_report(self, *, messages, context: UsageContext) -> list[UsageEvent]:
+ events = await self.extract(messages=messages, context=context)
+ await self.report(events=events)
+ return events
+
+ async def _close_sink(self, close) -> None: # noqa: ANN001
+ if inspect.iscoroutinefunction(close):
+ await close()
+ return
+ result_future: concurrent.futures.Future = concurrent.futures.Future()
+
+ def _run_sync_close() -> None:
+ try:
+ result_future.set_result(close())
+ except concurrent.futures.InvalidStateError:
+ # The timeout cancelled the waiter; the daemon thread may finish later.
+ pass
+ except Exception as exc:
+ try:
+ result_future.set_exception(exc)
+ except concurrent.futures.InvalidStateError:
+ pass
+
+ threading.Thread(
+ target=_run_sync_close,
+ name="openviking-usage-sink-close",
+ daemon=True,
+ ).start()
+ result = await asyncio.wrap_future(result_future)
+ if inspect.isawaitable(result):
+ await result
+
+ async def close(self) -> None:
+ for sink in self.sinks:
+ close = getattr(sink, "close", None)
+ if not callable(close):
+ continue
+ try:
+ await asyncio.wait_for(
+ self._close_sink(close),
+ timeout=self.sink_timeout_seconds,
+ )
+ except TimeoutError:
+ logger.warning(
+ "Usage sink close timed out after %.1fs: %s",
+ self.sink_timeout_seconds,
+ type(sink).__name__,
+ )
+ except Exception:
+ logger.exception("Usage sink close failed: %s", type(sink).__name__)
diff --git a/openviking/usage_reporter/sinks.py b/openviking/usage_reporter/sinks.py
new file mode 100644
index 000000000..213777afa
--- /dev/null
+++ b/openviking/usage_reporter/sinks.py
@@ -0,0 +1,13 @@
+# Copyright (c) 2026 Beijing Volcano Engine Technology Co., Ltd.
+# SPDX-License-Identifier: AGPL-3.0
+"""Usage event sinks."""
+
+from __future__ import annotations
+
+from typing import Protocol
+
+from .models import UsageEvent
+
+
+class UsageSink(Protocol):
+ async def write(self, *, events: list[UsageEvent]) -> None: ...
diff --git a/tests/session/test_session_usage_reporter.py b/tests/session/test_session_usage_reporter.py
new file mode 100644
index 000000000..14b24726e
--- /dev/null
+++ b/tests/session/test_session_usage_reporter.py
@@ -0,0 +1,68 @@
+# Copyright (c) 2026 Beijing Volcano Engine Technology Co., Ltd.
+# SPDX-License-Identifier: AGPL-3.0
+
+import pytest
+
+from openviking.message import ToolPart
+from openviking.server.dependencies import get_service
+from openviking.service.task_tracker import get_task_tracker
+from openviking.usage_reporter import MemoryUsageExtractor, UsageReporter
+
+
+async def _wait_for_task(task_id: str, timeout: float = 30.0) -> dict:
+ tracker = get_task_tracker()
+ for _ in range(int(timeout / 0.1)):
+ task = await tracker.get(task_id)
+ if task and task.status.value in ("completed", "failed"):
+ return task.to_dict()
+ import asyncio
+
+ await asyncio.sleep(0.1)
+ raise TimeoutError(f"Task {task_id} did not complete within {timeout}s")
+
+
+async def test_commit_reports_memory_usage_events_to_sink(session):
+ reported_events = []
+
+ class RecordingSink:
+ async def write(self, *, events):
+ reported_events.extend(events)
+
+ experience_uri = "viking://user/default/memories/experiences/no-order-exchange.md"
+ reporter = UsageReporter(
+ extractors=[MemoryUsageExtractor()],
+ sinks=[RecordingSink()],
+ )
+ get_service().sessions.set_usage_reporter(reporter)
+ session.add_message(
+ "user",
+ [
+ ToolPart(
+ tool_id="call-read",
+ tool_name="read_experience",
+ tool_status="completed",
+ tool_input={"uri": experience_uri},
+ )
+ ],
+ )
+
+ result = await session.commit_async(
+ memory_policy={
+ "self": {"enabled": False},
+ "peer": {"enabled": False},
+ "working_memory": {"enabled": False},
+ }
+ )
+ task = await _wait_for_task(result["task_id"])
+
+ assert task["status"] == "completed"
+ assert task["result"]["usage_events_extracted"] == 1
+ assert "usage_events_reported" not in task["result"]
+ assert len(reported_events) == 1
+ assert reported_events[0].event_type == "memory.injected"
+ assert reported_events[0].resource_uri == experience_uri
+ assert reported_events[0].resource_type == "experience"
+ assert reported_events[0].session_id == session.session_id
+ assert reported_events[0].evidence["archive_uri"] == result["archive_uri"]
+ assert reported_events[0].task_id == result["task_id"]
diff --git a/tests/unit/usage_reporter/test_memory_usage_extractor.py b/tests/unit/usage_reporter/test_memory_usage_extractor.py
new file mode 100644
index 000000000..ae21a7f69
--- /dev/null
+++ b/tests/unit/usage_reporter/test_memory_usage_extractor.py
@@ -0,0 +1,334 @@
+# Copyright (c) 2026 Beijing Volcano Engine Technology Co., Ltd.
+# SPDX-License-Identifier: AGPL-3.0
+
+import pytest
+
+from openviking.message import Message, TextPart, ToolPart
+from openviking.usage_reporter import (
+ MemoryUsageExtractor,
+ UsageContext,
+)
+
+
+def _context() -> UsageContext:
+ return UsageContext(
+ account_id="new",
+ user_id="test",
+ session_id="session-1",
+ archive_uri="viking://user/test/sessions/session-1/history/archive_001",
+ task_id="task-1",
+ )
+
+
+async def test_memory_usage_extractor_emits_recall_and_injection_events():
+ experience_uri = "viking://user/test/memories/experiences/no-order-exchange.md"
+ messages = [
+ Message(
+ id="msg-1",
+ role="user",
+ parts=[
+ TextPart("我要处理无订单号换货"),
+ ToolPart(
+ tool_id="call-search",
+ tool_name="search_experience",
+ tool_status="completed",
+ tool_input={"query": "无订单号换货"},
+ tool_output={"results": [{"uri": experience_uri}, {"uri": "viking://other"}]},
+ ),
+ ],
+ ),
+ Message(
+ id="msg-2",
+ role="user",
+ parts=[
+ ToolPart(
+ tool_id="call-read",
+ tool_name="read_experience",
+ tool_status="completed",
+ tool_input={"uri": experience_uri},
+ tool_output="## Situation\n用户未提供订单号但要求换货。",
+ )
+ ],
+ ),
+ Message(
+ id="msg-3",
+ role="user",
+ parts=[
+ ToolPart(
+ tool_id="call-pending",
+ tool_name="read_experience",
+ tool_status="running",
+ tool_input={"uri": experience_uri},
+ )
+ ],
+ ),
+ ]
+
+ events = await MemoryUsageExtractor().extract(messages=messages, context=_context())
+
+ assert [event.event_type for event in events] == ["memory.recalled", "memory.injected"]
+ assert [event.resource_uri for event in events] == [experience_uri, experience_uri]
+ assert [event.resource_type for event in events] == ["experience", "experience"]
+ assert events[0].evidence == {
+ "archive_uri": _context().archive_uri,
+ "message_id": "msg-1",
+ "tool_call_id": "call-search",
+ "tool_name": "search_experience",
+ }
+ assert events[1].evidence["tool_name"] == "read_experience"
+
+
+async def test_memory_usage_extractor_uses_message_time_for_event_time():
+ experience_uri = "viking://user/test/memories/experiences/no-order-exchange.md"
+ messages = [
+ Message(
+ id="msg-1",
+ role="user",
+ created_at="2026-07-10T20:30:40.123456+08:00",
+ parts=[
+ ToolPart(
+ tool_id="call-read",
+ tool_name="read_experience",
+ tool_status="completed",
+ tool_input={"uri": experience_uri},
+ )
+ ],
+ )
+ ]
+
+ events = await MemoryUsageExtractor().extract(messages=messages, context=_context())
+
+ assert events[0].occurred_at == "2026-07-10T12:30:40.123Z"
+
+
+async def test_memory_usage_extractor_ignores_non_experience_memory_uris():
+ messages = [
+ Message(
+ id="msg-1",
+ role="user",
+ parts=[
+ ToolPart(
+ tool_id="call-search",
+ tool_name="search_experience",
+ tool_status="completed",
+ tool_output={
+ "results": [
+ {"uri": "viking://user/default/memories/trajectories/a.md"},
+ {"uri": "viking://user/default/memories/preferences/a.md"},
+ ]
+ },
+ ),
+ ToolPart(
+ tool_id="call-read",
+ tool_name="read_experience",
+ tool_status="completed",
+ tool_input={"uri": "viking://user/default/memories/trajectories/a.md"},
+ ),
+ ],
+ )
+ ]
+
+ events = await MemoryUsageExtractor().extract(messages=messages, context=_context())
+
+ assert events == []
+
+
+async def test_memory_usage_extractor_ignores_other_users_experience_uris():
+ own_uri = "viking://user/test/memories/experiences/own.md"
+ other_uri = "viking://user/other/memories/experiences/other.md"
+ messages = [
+ Message(
+ id="msg-1",
+ role="user",
+ parts=[
+ ToolPart(
+ tool_id="call-search",
+ tool_name="search_experience",
+ tool_status="completed",
+ tool_output={"results": [{"uri": own_uri}, {"uri": other_uri}]},
+ ),
+ ToolPart(
+ tool_id="call-read",
+ tool_name="read_experience",
+ tool_status="completed",
+ tool_input={"uri": other_uri},
+ ),
+ ],
+ )
+ ]
+
+ events = await MemoryUsageExtractor().extract(messages=messages, context=_context())
+
+ assert [event.resource_uri for event in events] == [own_uri]
+
+
+async def test_memory_usage_extractor_ignores_noncanonical_experience_uris():
+ canonical_uri = "viking://user/test/memories/experiences/own.md"
+ query_alias = f"{canonical_uri}?source=codex"
+ fragment_alias = f"{canonical_uri}#approach"
+ messages = [
+ Message(
+ id="msg-1",
+ role="user",
+ parts=[
+ ToolPart(
+ tool_id="call-search",
+ tool_name="search_experience",
+ tool_status="completed",
+ tool_output={
+ "results": [
+ {"uri": canonical_uri},
+ {"uri": query_alias},
+ {"uri": fragment_alias},
+ ]
+ },
+ ),
+ ToolPart(
+ tool_id="call-read-query",
+ tool_name="read_experience",
+ tool_status="completed",
+ tool_input={"uri": query_alias},
+ ),
+ ToolPart(
+ tool_id="call-read-fragment",
+ tool_name="read_experience",
+ tool_status="completed",
+ tool_input={"uri": fragment_alias},
+ ),
+ ],
+ )
+ ]
+
+ events = await MemoryUsageExtractor().extract(messages=messages, context=_context())
+
+ assert [event.resource_uri for event in events] == [canonical_uri]
+
+
+async def test_memory_usage_extractor_ignores_internal_experience_sidecars():
+ custom_uri = "viking://user/test/memories/experiences/.custom-experience.md"
+ messages = [
+ Message(
+ id="msg-1",
+ role="user",
+ parts=[
+ ToolPart(
+ tool_id="call-search",
+ tool_name="search_experience",
+ tool_status="completed",
+ tool_output={
+ "results": [
+ {"uri": "viking://user/test/memories/experiences/.abstract.md"},
+ {"uri": "viking://user/test/memories/experiences/.overview.md"},
+ {"uri": custom_uri},
+ ]
+ },
+ ),
+ ToolPart(
+ tool_id="call-read",
+ tool_name="read_experience",
+ tool_status="completed",
+ tool_input={"uri": "viking://user/test/memories/experiences/.abstract.md"},
+ ),
+ ],
+ )
+ ]
+
+ events = await MemoryUsageExtractor().extract(messages=messages, context=_context())
+
+ assert [event.resource_uri for event in events] == [custom_uri]
+
+
+async def test_memory_usage_extractor_correlates_read_input_by_tool_id():
+ experience_uri = "viking://user/test/memories/experiences/long.md"
+ messages = [
+ Message(
+ id="msg-call",
+ role="assistant",
+ parts=[
+ ToolPart(
+ tool_id="call-read",
+ tool_name="read_experience",
+ tool_status="running",
+ tool_input={"uri": experience_uri},
+ )
+ ],
+ ),
+ Message(
+ id="msg-result",
+ role="user",
+ parts=[
+ ToolPart(
+ tool_id="call-read",
+ tool_name="read_experience",
+ tool_status="completed",
+ tool_output='{"uri":"truncated',
+ )
+ ],
+ ),
+ ]
+
+ events = await MemoryUsageExtractor().extract(messages=messages, context=_context())
+
+ assert [event.event_type for event in events] == ["memory.injected"]
+ assert events[0].resource_uri == experience_uri
+
+
+async def test_memory_usage_extractor_replay_uses_stable_event_id():
+ experience_uri = "viking://user/test/memories/experiences/replay.md"
+ messages = [
+ Message(
+ id="msg-replay",
+ role="user",
+ created_at="2026-07-16T10:00:00Z",
+ parts=[
+ ToolPart(
+ tool_id="call-replay",
+ tool_name="read_experience",
+ tool_status="completed",
+ tool_input={"uri": experience_uri},
+ )
+ ],
+ )
+ ]
+ extractor = MemoryUsageExtractor()
+
+ first = await extractor.extract(messages=messages, context=_context())
+ replay = await extractor.extract(messages=messages, context=_context())
+
+ assert first[0].event_id
+ assert replay[0].event_id == first[0].event_id
+
+
+async def test_memory_usage_extractor_ignores_completed_tools_without_tool_id():
+ experience_uri = "viking://user/test/memories/experiences/missing-tool-id.md"
+ messages = [
+ Message(
+ id="msg-missing-tool-id",
+ role="user",
+ parts=[
+ ToolPart(
+ tool_name="search_experience",
+ tool_status="completed",
+ tool_output={"results": [{"uri": experience_uri}]},
+ ),
+ ToolPart(
+ tool_name="read_experience",
+ tool_status="completed",
+ tool_input={"uri": experience_uri},
+ ),
+ ],
+ )
+ ]
+
+ events = await MemoryUsageExtractor().extract(messages=messages, context=_context())
+
+ assert events == []
diff --git a/tests/unit/usage_reporter/test_reporter.py b/tests/unit/usage_reporter/test_reporter.py
new file mode 100644
index 000000000..d58d995ad
--- /dev/null
+++ b/tests/unit/usage_reporter/test_reporter.py
@@ -0,0 +1,165 @@
+# Copyright (c) 2026 Beijing Volcano Engine Technology Co., Ltd.
+# SPDX-License-Identifier: AGPL-3.0
+
+import asyncio
+import threading
+
+from openviking.usage_reporter import UsageContext, UsageEvent, UsageReporter
+
+
+def _context() -> UsageContext:
+ return UsageContext(
+ account_id="new",
+ user_id="test",
+ session_id="session-1",
+ archive_uri="viking://user/test/sessions/session-1/history/archive_001",
+ task_id="task-1",
+ )
+
+
+def _event() -> UsageEvent:
+ context = _context()
+ return UsageEvent(
+ event_type="memory.injected",
+ resource_uri="viking://user/test/memories/experiences/a.md",
+ resource_type="experience",
+ account_id=context.account_id,
+ user_id=context.user_id,
+ session_id=context.session_id,
+ task_id=context.task_id,
+ occurred_at="2026-07-10T12:00:00Z",
+ evidence={"archive_uri": context.archive_uri},
+ )
+
+
+async def test_extractor_failure_is_ignored():
+ class FailingExtractor:
+ name = "failing"
+
+ async def extract(self, *, messages, context):
+ raise RuntimeError("extract failed")
+
+ reporter = UsageReporter(extractors=[FailingExtractor()])
+
+ assert await reporter.extract(messages=[], context=_context()) == []
+
+
+async def test_sink_failure_does_not_stop_later_sinks():
+ writes = []
+
+ class FailingSink:
+ async def write(self, *, events):
+ raise RuntimeError("sink failed")
+
+ class RecordingSink:
+ async def write(self, *, events):
+ writes.extend(events)
+
+ event = _event()
+ reporter = UsageReporter(sinks=[FailingSink(), RecordingSink()])
+
+ await reporter.report(events=[event])
+
+ assert writes == [event]
+
+
+async def test_sink_timeout_does_not_stop_later_sinks():
+ writes = []
+
+ class HangingSink:
+ async def write(self, *, events):
+ await asyncio.sleep(1)
+
+ class RecordingSink:
+ async def write(self, *, events):
+ writes.extend(events)
+
+ event = _event()
+ reporter = UsageReporter(
+ sinks=[HangingSink(), RecordingSink()],
+ sink_timeout_seconds=0.01,
+ )
+
+ await reporter.report(events=[event])
+
+ assert writes == [event]
+
+
+async def test_close_calls_optional_sink_close():
+ closed = []
+
+ class ClosableSink:
+ async def write(self, *, events):
+ return None
+
+ async def close(self):
+ closed.append(True)
+
+ reporter = UsageReporter(sinks=[ClosableSink()])
+
+ await reporter.close()
+
+ assert closed == [True]
+
+
+async def test_sync_close_timeout_does_not_block_later_sinks():
+ closed = []
+ release_sync_close = threading.Event()
+ sync_close_finished = threading.Event()
+ sync_close_daemon = []
+
+ class BlockingSyncSink:
+ def close(self):
+ closed.append("sync-started")
+ sync_close_daemon.append(threading.current_thread().daemon)
+ release_sync_close.wait(timeout=1)
+ sync_close_finished.set()
+
+ class AsyncSink:
+ async def close(self):
+ closed.append("async")
+
+ reporter = UsageReporter(
+ sinks=[BlockingSyncSink(), AsyncSink()],
+ sink_timeout_seconds=0.005,
+ )
+
+ try:
+ await reporter.close()
+
+ assert closed == ["sync-started", "async"]
+ assert sync_close_daemon == [True]
+ assert not sync_close_finished.is_set()
+ finally:
+ release_sync_close.set()
+ sync_close_finished.wait(timeout=0.1)
+
+
+async def test_sinks_are_reported_concurrently():
+ started = set()
+ both_started = asyncio.Event()
+ release = asyncio.Event()
+
+ class BlockingSink:
+ def __init__(self, name):
+ self.name = name
+
+ async def write(self, *, events):
+ del events
+ started.add(self.name)
+ if len(started) == 2:
+ both_started.set()
+ await release.wait()
+
+ reporter = UsageReporter(
+ sinks=[BlockingSink("first"), BlockingSink("second")],
+ sink_timeout_seconds=0.5,
+ )
+ task = asyncio.create_task(reporter.report(events=[_event()]))
+ try:
+ await asyncio.wait_for(both_started.wait(), timeout=0.1)
+ finally:
+ release.set()
+ await task
+
+ assert started == {"first", "second"}
diff --git a/tests/unit/usage_reporter/test_usage_reporter_config.py b/tests/unit/usage_reporter/test_usage_reporter_config.py
new file mode 100644
index 000000000..46b7715a8
--- /dev/null
+++ b/tests/unit/usage_reporter/test_usage_reporter_config.py
@@ -0,0 +1,140 @@
+# Copyright (c) 2026 Beijing Volcano Engine Technology Co., Ltd.
+# SPDX-License-Identifier: AGPL-3.0
+
+import json
+import sys
+from contextlib import asynccontextmanager
+
+import pytest
+
+from openviking.server.app import create_app
+from openviking.server.config import ServerConfig, UsageReporterConfig
+from openviking.usage_reporter import UsageContext, UsageEvent
+from openviking.usage_reporter.config import build_usage_reporter
+
+
+async def test_custom_sink_is_loaded_from_class_path(tmp_path, monkeypatch):
+ module_dir = tmp_path / "custom_sink_pkg"
+ module_dir.mkdir()
+ (module_dir / "__init__.py").write_text("", encoding="utf-8")
+ output_path = tmp_path / "custom-events.jsonl"
+ (module_dir / "sink.py").write_text(
+ """
+import json
+
+class CustomUsageSink:
+ def __init__(self, path):
+ self.path = path
+
+ async def write(self, *, events):
+ with open(self.path, "a", encoding="utf-8") as f:
+ for event in events:
+ f.write(json.dumps(event.to_dict(), ensure_ascii=False) + "\\n")
+""",
+ encoding="utf-8",
+ )
+ monkeypatch.syspath_prepend(str(tmp_path))
+ sys.modules.pop("custom_sink_pkg.sink", None)
+
+ reporter = build_usage_reporter(
+ UsageReporterConfig(
+ enabled=True,
+ extractors=["memory_usage"],
+ sinks=[
+ {
+ "type": "custom",
+ "class_path": "custom_sink_pkg.sink.CustomUsageSink",
+ "config": {"path": str(output_path)},
+ }
+ ],
+ )
+ )
+ context = UsageContext(
+ account_id="new",
+ user_id="test",
+ session_id="session-1",
+ archive_uri="viking://user/test/sessions/session-1/history/archive_001",
+ task_id="task-1",
+ )
+ event = UsageEvent(
+ event_type="memory.injected",
+ resource_uri="viking://user/test/memories/experiences/a.md",
+ resource_type="experience",
+ account_id="new",
+ user_id="test",
+ session_id="session-1",
+ task_id="task-1",
+ occurred_at="2026-07-09T12:00:00Z",
+ evidence={"archive_uri": context.archive_uri},
+ )
+
+ await reporter.report(events=[event])
+
+ payload = json.loads(output_path.read_text(encoding="utf-8").splitlines()[0])
+ assert payload["event_type"] == "memory.injected"
+ assert payload["resource_uri"] == "viking://user/test/memories/experiences/a.md"
+ assert payload["resource_type"] == "experience"
+ assert "memory_uri" not in payload
+ assert "source" not in payload
+
+
+async def test_app_reuses_and_closes_usage_reporter(monkeypatch):
+ built_reporters = []
+ assigned_reporters = []
+
+ class Reporter:
+ closed = False
+
+ async def close(self):
+ self.closed = True
+
+ reporter = Reporter()
+
+ def build_reporter(config):
+ del config
+ built_reporters.append(reporter)
+ return reporter
+
+ class Sessions:
+ def set_tool_output_externalization_config(self, config):
+ del config
+
+ def set_usage_reporter(self, value):
+ assigned_reporters.append(value)
+
+ class Service:
+ sessions = Sessions()
+
+ class TaskTracker:
+ def start_cleanup_loop(self):
+ return None
+
+ def stop_cleanup_loop(self):
+ return None
+
+ async def initialize_runtime_state(app, service, config):
+ del app, service, config
+
+ @asynccontextmanager
+ async def mcp_lifespan():
+ yield
+
+ monkeypatch.setattr(
+ "openviking.usage_reporter.config.build_usage_reporter",
+ build_reporter,
+ )
+ monkeypatch.setattr(
+ "openviking.server.app._initialize_runtime_state",
+ initialize_runtime_state,
+ )
+ monkeypatch.setattr("openviking.server.app.get_task_tracker", lambda: TaskTracker())
+ monkeypatch.setattr("openviking.server.mcp_endpoint.mcp_lifespan", mcp_lifespan)
+
+ app = create_app(config=ServerConfig(), service=Service())
+ async with app.router.lifespan_context(app):
+ pass
+
+ assert built_reporters == [reporter]
+ assert assigned_reporters == [reporter, reporter]
+ assert reporter.closed is True