Self-evolving Context Database for AI Agents. Unify Agent Memory, Knowledge RAG and Skills.
Python agent-contextagent-memoryagent-pluginsagentic-ragcontext-databasedsh-pluginknowledge-basememorymemory-managementself-evolvingvector-database
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.mdnew file mode 100644index 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.mjsindex 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.jsonindex 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.mjsindex 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.mjsnew file mode 100644index 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.mjsindex 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.mjsindex 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.mjsnew file mode 100644index 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.mjsnew file mode 100644index 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.mjsindex 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.mjsindex 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.mdnew file mode 100644index 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.mjsindex 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.mjsindex 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.mdnew file mode 100644index 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.pyindex 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: ANN001sessions = 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)@asynccontextmanagerasync 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.pyindex 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 enabledapi_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 headerdiff --git a/openviking/service/session_service.py b/openviking/service/session_service.pyindex 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 UsageReporterclass SessionService:@@ -43,6 +44,7 @@ class SessionService:self._viking_fs = viking_fsself._session_compressor = session_compressorself._tool_output_externalization_config = ToolOutputExternalizationConfig()+ self._usage_reporter: Optional["UsageReporter"] = Nonedef 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.pyindex d5450527c..4eaca02c1 100644--- a/openviking/session/session.py+++ b/openviking/session/session.py@@ -47,6 +47,7 @@ if TYPE_CHECKING:from openviking.storage import VikingDBManagerfrom openviking.storage.queuefs.session_commit_msg import SessionCommitMsgfrom openviking.storage.viking_fs import VikingFS+ from openviking.usage_reporter import UsageReporterlogger = 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_fsself._vikingdb_manager = vikingdb_manager@@ -391,6 +393,7 @@ class Session:if tool_output_externalization_config is not Noneelse ToolOutputExternalizationConfig())+ self._usage_reporter = usage_reporterlogger.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 = 0extracted_skill_results: list[dict] = []active_count_updated = 0memory_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_resultsif 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__.pynew file mode 100644index 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.pynew file mode 100644index 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.pynew file mode 100644index 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.pynew file mode 100644index 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.pynew file mode 100644index 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.pynew file mode 100644index 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.pynew file mode 100644index 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.pynew file mode 100644index 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.pynew file mode 100644index 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.pynew file mode 100644index 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