@openviking/opencode-plugin 0.2.3 → 0.2.4

package/INSTALL-ZH.md

@@ -110,6 +110,9 @@ export { OpenVikingPlugin, default } from "./openviking/index.mjs"
 }
 ```
 
+`autoRecall.limit` 是遗留的配额缩放输入，不是最终结果上限。显式设置为
+1 到 5 时，有效总配额仍为 6，因为六个 coding 分类会各保留一个检索槽位。
+
 推荐通过环境变量提供 API Key，而不是写入配置文件：
 
 ```bash
@@ -137,7 +140,6 @@ user/admin API key 的 API_KEY mode 时应留空。
 - `openviking_read`、`openviking_list`、`openviking_grep`、`openviking_glob`
 - `openviking_remember`、`openviking_add_resource`、`openviking_forget`、`openviking_health`
 - `openviking_list_watches`、`openviking_cancel_watch`
-- `openviking_code_search`、`openviking_code_outline`、`openviking_code_expand`
 
 如果行为异常，先查看运行时文件：
 
@@ -167,7 +169,6 @@ curl http://localhost:1933/health
 - `openviking_add_resource`：添加 URL、本地文件、sitemap 或 feed
 - `openviking_forget`：在用户明确确认后删除 `viking://` URI
 - `openviking_list_watches` / `openviking_cancel_watch`：查看或取消资源 watch
-- `openviking_code_search`、`openviking_code_outline`、`openviking_code_expand`：查看已索引代码符号
 - `openviking_health`：检查 OpenViking server 健康状态
 
 使用建议：

package/INSTALL.md

@@ -110,6 +110,10 @@ Example configuration:
 }
 ```
 
+`autoRecall.limit` is a legacy quota-scaling input, not a final result cap.
+Explicit values from 1 through 5 produce an effective total quota of 6 because
+each coding category keeps one retrieval slot.
+
 It is recommended to provide the API key through an environment variable instead of writing it into the configuration file:
 
 ```bash
@@ -132,7 +136,6 @@ In a new OpenCode session, ask the agent to browse OpenViking memory or search f
 - `openviking_read`, `openviking_list`, `openviking_grep`, `openviking_glob`
 - `openviking_remember`, `openviking_add_resource`, `openviking_forget`, `openviking_health`
 - `openviking_list_watches`, `openviking_cancel_watch`
-- `openviking_code_search`, `openviking_code_outline`, `openviking_code_expand`
 
 If anything looks wrong, check the runtime files:
 
@@ -162,7 +165,6 @@ The plugin registers OpenViking's stdio MCP proxy through OpenCode config. The s
 - `openviking_add_resource`: add a URL, local file, sitemap, or feed.
 - `openviking_forget`: delete a `viking://` URI after explicit user confirmation.
 - `openviking_list_watches` / `openviking_cancel_watch`: inspect or cancel resource watches.
-- `openviking_code_search`, `openviking_code_outline`, `openviking_code_expand`: inspect indexed code symbols.
 - `openviking_health`: check OpenViking server health.
 
 Usage guidance:

package/README.md

@@ -132,7 +132,12 @@ Create `~/.config/opencode/openviking-config.json`:
 }
 ```
 
-API keys are resolved from environment variables or `~/.openviking/ovcli.conf` and sent as `Authorization: Bearer ...` by both hooks and the MCP proxy. `account` and `user` are trusted-mode identity
+`autoRecall.limit` is a legacy quota-scaling input, not a final result cap.
+Explicit values from 1 through 5 produce an effective total quota of 6 because
+each coding category keeps one retrieval slot. Use Context `quotas` directly
+when exact category ceilings are required.
+
+API keys are resolved from environment variables or `~/.openviking/ovcli.conf` and sent as `Authorization: Bearer ...` by both hooks and the MCP proxy. Recall goes through the server-side context face (`POST /api/v1/search/search` with `mode="context"`), falling back to the deprecated `/api/v1/search/recall` on older deployments. `account` and `user` are trusted-mode identity
 headers sent as `X-OpenViking-Account` and `X-OpenViking-User`; leave them empty
 when using API-key mode with user/admin API keys.
 By default the plugin derives a peer from the project directory using Claude's
@@ -177,7 +182,6 @@ OpenCode sees the OpenViking MCP server as `openviking`, so tool names are names
 - `openviking_add_resource`: add a URL, local file, sitemap, or feed.
 - `openviking_forget`: delete a `viking://` URI after explicit user confirmation.
 - `openviking_list_watches` / `openviking_cancel_watch`: inspect or cancel resource watches.
-- `openviking_code_search`, `openviking_code_outline`, `openviking_code_expand`: inspect indexed code symbols.
 - `openviking_health`: check OpenViking server health.
 
 The proxy forwards the server's real `tools/list` response; the plugin does not maintain a separate native tool list.

package/index.mjs

@@ -24,7 +24,7 @@ export async function OpenVikingPlugin({ client, directory }) {
 
   const repoContext = createRepoContext({ config })
   const sessionManager = createMemorySessionManager({ config, pluginRoot: dataDir })
-  const recall = createMemoryRecall({ config })
+  const recall = createMemoryRecall({ config, sessionManager })
   const sessionInject = createSessionInject({ config, sessionManager })
   const vikingUriGuard = createVikingUriGuard()
 

package/lib/config.mjs

@@ -1,9 +1,14 @@
 import fs from "fs"
 import path from "path"
 import { homedir } from "os"
-import { resolveOpenVikingCredentials } from "./shared/credentials.mjs"
+import { buildUserAgent, readManifestVersion, resolveOpenVikingCredentials } from "./shared/credentials.mjs"
 import { resolveEffectivePeerId } from "./shared/workspace-peer.mjs"
 
+const USER_AGENT = buildUserAgent(
+  "opencode",
+  readManifestVersion(new URL("../package.json", import.meta.url)),
+)
+
 const DEFAULT_CONFIG = {
   endpoint: "http://127.0.0.1:1933",
   apiKey: "",
@@ -12,6 +17,9 @@ const DEFAULT_CONFIG = {
   peerId: "",
   workspacePeer: true,
   recallPeerScope: "all",
+  // Server-side query expansion costs a model call before retrieval starts, so
+  // it has to be switchable from the client that pays the latency.
+  recallQueryExpansion: "auto",
   enabled: true,
   timeoutMs: 30000,
   runtime: {
@@ -23,7 +31,7 @@ const DEFAULT_CONFIG = {
   },
   autoRecall: {
     enabled: true,
-    limit: 6,
+    limit: 10,
     scoreThreshold: 0.35,
     maxContentChars: 500,
     preferAbstract: true,
@@ -123,6 +131,8 @@ function applyBehaviorConfig(config, fileConfig = {}) {
   }
 
   const autoRecall = fileConfig.autoRecall ?? {}
+  config.recallLimitConfigured = autoRecall.limit !== undefined ||
+    fileConfig.recallLimit !== undefined
   config.autoRecall = {
     ...DEFAULT_CONFIG.autoRecall,
     ...autoRecall,
@@ -152,9 +162,11 @@ function applyBehaviorConfig(config, fileConfig = {}) {
     "debugLogPath",
     "workspacePeer",
     "recallPeerScope",
+    "recallQueryExpansion",
   ]) {
     if (fileConfig[key] !== undefined) config[key] = fileConfig[key]
   }
+  config.recallQueryExpansionConfigured = fileConfig.recallQueryExpansion !== undefined
 }
 
 function applyEnv(config) {
@@ -162,7 +174,10 @@ function applyEnv(config) {
   if (process.env.OPENVIKING_AUTO_RECALL !== undefined) {
     config.autoRecall.enabled = envBool("OPENVIKING_AUTO_RECALL") ?? config.autoRecall.enabled
   }
-  if (process.env.OPENVIKING_RECALL_LIMIT) config.autoRecall.limit = process.env.OPENVIKING_RECALL_LIMIT
+  if (process.env.OPENVIKING_RECALL_LIMIT) {
+    config.autoRecall.limit = process.env.OPENVIKING_RECALL_LIMIT
+    config.recallLimitConfigured = true
+  }
   if (process.env.OPENVIKING_SCORE_THRESHOLD) config.autoRecall.scoreThreshold = process.env.OPENVIKING_SCORE_THRESHOLD
   if (process.env.OPENVIKING_RECALL_MAX_CONTENT_CHARS) {
     config.autoRecall.maxContentChars = process.env.OPENVIKING_RECALL_MAX_CONTENT_CHARS
@@ -172,6 +187,10 @@ function applyEnv(config) {
     config.autoRecall.preferAbstract = envBool("OPENVIKING_RECALL_PREFER_ABSTRACT") ?? config.autoRecall.preferAbstract
   }
   if (process.env.OPENVIKING_RECALL_PEER_SCOPE) config.recallPeerScope = process.env.OPENVIKING_RECALL_PEER_SCOPE
+  if (process.env.OPENVIKING_RECALL_QUERY_EXPANSION) {
+    config.recallQueryExpansion = process.env.OPENVIKING_RECALL_QUERY_EXPANSION
+    config.recallQueryExpansionConfigured = true
+  }
   if (process.env.OPENVIKING_WORKSPACE_PEER !== undefined) {
     config.workspacePeer = envBool("OPENVIKING_WORKSPACE_PEER") ?? config.workspacePeer
   }
@@ -216,6 +235,7 @@ function normalizeConfig(config) {
   config.baseUrl = config.endpoint
   config.accountId = config.account
   config.userId = config.user
+  config.userAgent = USER_AGENT
   config.timeoutMs = normalizeNumber(config.timeoutMs, DEFAULT_CONFIG.timeoutMs, 1000, 300000)
   config.repoContext.cacheTtlMs = normalizeNumber(
     config.repoContext.cacheTtlMs,
@@ -223,17 +243,25 @@ function normalizeConfig(config) {
     1000,
     60 * 60 * 1000,
   )
-  config.autoRecall.limit = Math.max(1, Math.min(50, Math.round(Number(config.autoRecall.limit) || 6)))
+  config.autoRecall.limit = Math.max(1, Math.min(50, Math.round(Number(config.autoRecall.limit) || 10)))
   config.autoRecall.scoreThreshold = Math.max(0, Math.min(1, Number(config.autoRecall.scoreThreshold) || 0))
   config.autoRecall.maxContentChars = Math.max(100, Math.min(5000, Math.round(Number(config.autoRecall.maxContentChars) || 500)))
   config.autoRecall.tokenBudget = Math.max(200, Math.min(50000, Math.round(Number(config.autoRecall.tokenBudget) || 2000)))
   config.autoRecall.minQueryLength = Math.max(1, Math.min(64, Math.round(Number(config.autoRecall.minQueryLength) || 3)))
   config.captureMode = config.captureMode === "keyword" ? "keyword" : "semantic"
   config.recallPeerScope = config.recallPeerScope === "actor" ? "actor" : "all"
+  config.recallQueryExpansion = config.recallQueryExpansion === "off" ? "off" : "auto"
   config.captureMaxLength = Math.max(200, Math.min(100000, Math.round(Number(config.captureMaxLength) || 24000)))
   config.captureToolMaxChars = Math.max(200, Math.min(20000, Math.round(Number(config.captureToolMaxChars) || 2000)))
   config.commitTokenThreshold = Math.max(1000, Math.round(Number(config.commitTokenThreshold) || 20000))
-  config.commitKeepRecentCount = Math.max(0, Math.round(Number(config.commitKeepRecentCount) || 10))
+  const rawCommitKeepRecentCount = config.commitKeepRecentCount
+  const commitKeepRecentCount = rawCommitKeepRecentCount == null ||
+    (typeof rawCommitKeepRecentCount === "string" && rawCommitKeepRecentCount.trim() === "")
+    ? Number.NaN
+    : Number(rawCommitKeepRecentCount)
+  config.commitKeepRecentCount = Number.isFinite(commitKeepRecentCount)
+    ? Math.max(0, Math.round(commitKeepRecentCount))
+    : DEFAULT_CONFIG.commitKeepRecentCount
   config.profileTokenBudget = Math.max(500, Math.round(Number(config.profileTokenBudget) || 10000))
   config.resumeContextBudget = Math.max(1024, Math.round(Number(config.resumeContextBudget) || 32000))
   if (!Array.isArray(config.bypassSessionPatterns)) config.bypassSessionPatterns = []

package/lib/memory-recall.mjs

@@ -2,14 +2,15 @@ import { buildRecallBlock } from "./shared/recall-core.mjs"
 import { isBypassed } from "./shared/session-model.mjs"
 import { effectivePeerId, fetchJSON, log } from "./utils.mjs"
 
-export function createMemoryRecall({ config }) {
+export function createMemoryRecall({ config, sessionManager }) {
   async function injectRelevantMemories(input, output) {
     if (!config.autoRecall?.enabled) return
     const query = extractCurrentUserText(output.parts ?? [])
     if (!query) return
     if (query.length < config.minQueryLength) return
+    const sessionID = input.sessionID ?? output.message?.sessionID
     if (isBypassed(config, {
-      sessionId: input.sessionID ?? output.message?.sessionID,
+      sessionId: sessionID,
       cwd: input.directory ?? input.cwd,
     })) return
 
@@ -17,11 +18,18 @@ export function createMemoryRecall({ config }) {
     if (!health.ok) return
 
     const block = await buildRecallBlock(
-      (path, init = {}, options = {}) => fetchJSON(config, path, init, { ...options, timeoutMs: 5000 }),
+      // 5s is this hook's own budget for a bare retrieval; when the request
+      // also spends a server fuse the helper hands down a longer deadline, and
+      // overriding it here would abort a request the server was still inside.
+      (path, init = {}, options = {}) =>
+        fetchJSON(config, path, init, { ...options, timeoutMs: options.timeoutMs ?? 5000 }),
       config,
       query,
       {
         actorPeerId: effectivePeerId(config),
+        // The mapped OV session is what turns on server-side query expansion
+        // and the cross-turn dedup ledger.
+        sessionId: sessionID ? sessionManager.getMappedSessionId(sessionID) : "",
         log: (stage, data) => log("DEBUG", "recall", stage, data),
       },
     )
@@ -35,12 +43,13 @@ export function createMemoryRecall({ config }) {
   return { injectRelevantMemories }
 }
 
-function extractCurrentUserText(parts) {
+export function extractCurrentUserText(parts) {
   const texts = []
   for (const part of parts) {
     if (part.type !== "text" || typeof part.text !== "string") continue
+    if (part.synthetic || part.ignored) continue
     if (part.text.includes("<openviking-context")) return null
-    if (!part.synthetic && !part.ignored) texts.push(part.text)
+    texts.push(part.text)
   }
   const joined = texts.join(" ").trim()
   return joined || null

package/lib/memory-session.mjs

@@ -15,6 +15,9 @@ import {
 import {
   sendSessionMessages,
 } from "./shared/batch-send.mjs"
+import {
+  isRetryableFailure,
+} from "./shared/retryable.mjs"
 import {
   log,
   effectivePeerId,
@@ -29,7 +32,7 @@ export function createMemorySessionManager({ config, pluginRoot }) {
   let saveTimer = null
 
   async function init() {
-    await migrateLegacySessionMap()
+    if (config.autoCapture) await migrateLegacySessionMap()
     await loadState()
     const health = await fetchJSON(config, "/health", {}, { timeoutMs: 5000 })
     if (health.ok) {
@@ -140,9 +143,9 @@ export function createMemorySessionManager({ config, pluginRoot }) {
       await handleSessionCompacted(event)
     } else if (event.type === "session.idle") {
       await handleSessionIdle(event)
-    } else if (event.type === "message.updated") {
+    } else if (event.type === "message.updated" && config.autoCapture) {
       await handleMessageUpdated(event)
-    } else if (event.type === "message.part.updated") {
+    } else if (event.type === "message.part.updated" && config.autoCapture) {
       await handleMessagePartUpdated(event)
     }
   }
@@ -259,7 +262,7 @@ export function createMemorySessionManager({ config, pluginRoot }) {
     if (!state) return false
 
     const added = await flushPendingMessages(opencodeSessionId, state)
-    if (commit) {
+    if (commit && config.autoCapture) {
       await commitOvSession(state.ovSessionId, { force: true, reason })
     } else if (added > 0) {
       await maybeCommitByThreshold(state)
@@ -361,6 +364,7 @@ export function createMemorySessionManager({ config, pluginRoot }) {
   }
 
   async function flushPendingMessages(opencodeSessionId, state) {
+    if (!config.autoCapture) return 0
     const toSend = []
     for (const [messageId, message] of state.messages.entries()) {
       if (message.captured) continue
@@ -474,9 +478,4 @@ export function createMemorySessionManager({ config, pluginRoot }) {
     }
   }
 
-  function isRetryableFailure(res) {
-    if (!res || res.ok) return false
-    const status = Number(res.status || 0)
-    return !status || status >= 500 || status === 408 || status === 429
-  }
 }

package/lib/runtime.mjs

@@ -6,6 +6,7 @@ export async function checkServiceHealth(config, timeoutMs = 3000) {
   try {
     const response = await fetch(`${normalizeEndpoint(config.endpoint)}/health`, {
       method: "GET",
+      headers: config.userAgent ? { "User-Agent": config.userAgent } : undefined,
       signal: controller.signal,
     })
     return response.ok

package/lib/shared/batch-send.mjs

@@ -1,12 +1,11 @@
 // GENERATED FROM examples/memory-plugin-shared/lib. DO NOT EDIT.
 import { enqueue } from "./pending-queue.mjs";
+import { isRetryableFailure } from "./retryable.mjs";
 
 export const BATCH_LIMIT = 100;
 
 export function isRetryableSendFailure(res) {
-  if (!res || res.ok) return false;
-  const status = Number(res.status || 0);
-  return !status || status === 408 || status === 429 || status >= 500;
+  return isRetryableFailure(res);
 }
 
 function makeResult() {

package/lib/shared/capture-utils.mjs

@@ -99,7 +99,6 @@ function toolName(block) {
     block?.toolName ||
     block?.function?.name ||
     block?.call?.name ||
-    block?.id ||
     "",
   );
 }
@@ -128,7 +127,6 @@ function toolPayload(block, kind) {
 
 function toolId(block) {
   return oneLine(
-    block?.id ||
     block?.call_id ||
     block?.callId ||
     block?.tool_call_id ||
@@ -137,6 +135,7 @@ function toolId(block) {
     block?.toolUseId ||
     block?.function_call_id ||
     block?.functionCallId ||
+    block?.id ||
     "",
   );
 }

package/lib/shared/credentials.mjs

@@ -30,6 +30,27 @@ function tryLoadJson(path) {
   }
 }
 
+/**
+ * Build the User-Agent every harness plugin sends on OpenViking-bound requests.
+ * Shape is `name/semver` so downstream stats layers can parse it as one token.
+ */
+export function buildUserAgent(harness, version) {
+  return `openviking-memory-${harness}/${str(version, "") || "0.0.0"}`;
+}
+
+/**
+ * Read a plugin manifest's `version` field. Accepts a path or a URL (so callers
+ * can resolve relative to import.meta.url). Returns "" when unreadable so the
+ * User-Agent falls back to 0.0.0 instead of throwing inside a short-lived hook.
+ */
+export function readManifestVersion(manifest) {
+  try {
+    return str(JSON.parse(readFileSync(manifest, "utf-8")).version, "");
+  } catch {
+    return "";
+  }
+}
+
 function looksLikeOvcli(obj) {
   if (!obj || typeof obj !== "object") return false;
   if (obj.server && typeof obj.server === "object") return false;

package/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);
@@ -215,6 +253,7 @@ export function createOpenVikingMcpProxy({
     if (proxyConfig.account) headers["X-OpenViking-Account"] = proxyConfig.account;
     if (proxyConfig.user) headers["X-OpenViking-User"] = proxyConfig.user;
     if (proxyConfig.peerId) headers["X-OpenViking-Actor-Peer"] = proxyConfig.peerId;
+    if (proxyConfig.userAgent) headers["User-Agent"] = proxyConfig.userAgent;
     return headers;
   }
 
@@ -381,6 +420,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 +442,7 @@ export function createOpenVikingMcpProxy({
         return;
       }
       for (const outbound of result.messages) {
-        await writeMessage(outbound);
+        await writeMessage(appendLocalTools(message, outbound));
       }
     } catch (err) {
       if (expectsResponse) {

package/lib/shared/pending-queue.mjs

@@ -24,6 +24,7 @@ import { mkdir, readdir, readFile, rename, writeFile, unlink, stat, chmod } from
 import { createHash } from "node:crypto";
 import { join } from "node:path";
 import { homedir } from "node:os";
+import { isRetryableFailure } from "./retryable.mjs";
 
 const DEFAULT_MAX_RETRIES = 3;
 const DEFAULT_TTL_DAYS = 7;
@@ -109,9 +110,7 @@ function pendingFromProcessingFilename(filename) {
 }
 
 function isRetryableReplayFailure(res) {
-  if (!res || res.ok) return false;
-  const status = Number(res.status || 0);
-  return !status || status >= 500 || status === 408 || status === 429;
+  return isRetryableFailure(res);
 }
 
 async function readEntry(dir, filename) {

package/lib/shared/plugin-config.mjs

@@ -0,0 +1,90 @@
+// GENERATED FROM examples/memory-plugin-shared/lib. DO NOT EDIT.
+/**
+ * Per-harness plugin settings from ovcli.conf.
+ *
+ * ovcli.conf carried connection fields only, so every harness had to keep its
+ * tuning knobs in ov.conf's harness section — a server-side file that a
+ * client-side plugin has no business editing. The `plugin` section fixes that:
+ * shared keys apply to every harness that reads them, and a per-harness object
+ * overrides them.
+ *
+ *   {
+ *     "url": "...", "api_key": "...",
+ *     "plugin": {
+ *       "recallQueryExpansion": "off",
+ *       "recallCompress": "auto"
+ *     }
+ *   }
+ *
+ * Resolution stays env → ovcli.conf plugin.<harness> → ovcli.conf plugin →
+ * ov.conf harness section (legacy) → defaults.
+ *
+ * Consumers: Claude Code and Codex only. The other harnesses ship this module
+ * through `sync.mjs` but still read their knobs from the environment, so a
+ * `plugin` entry named after them is inert. `HARNESS_KEYS` lists what a harness
+ * loader actually consumes today — add a key here as its loader starts calling
+ * `loadPluginSettings`, not before, so the section never promises a knob that
+ * silently does nothing.
+ */
+
+import { readFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join, resolve as resolvePath } from "node:path";
+
+const DEFAULT_OVCLI_CONF_PATH = join(homedir(), ".openviking", "ovcli.conf");
+
+export const HARNESS_KEYS = {
+  claudeCode: "claude_code",
+  codex: "codex",
+};
+
+function tryLoadJson(path) {
+  try {
+    return JSON.parse(readFileSync(path, "utf-8"));
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Merge the shared plugin section with the harness-specific override.
+ * Returns a flat settings object; unknown keys pass through untouched so a
+ * harness can add its own knobs without touching this module.
+ */
+export function loadPluginSettings(harness, env = process.env) {
+  const path = resolvePath(
+    (env.OPENVIKING_CLI_CONFIG_FILE || DEFAULT_OVCLI_CONF_PATH).replace(/^~/, homedir()),
+  );
+  const file = tryLoadJson(path);
+  const plugin = file && typeof file.plugin === "object" && file.plugin ? file.plugin : {};
+
+  const shared = {};
+  for (const [key, value] of Object.entries(plugin)) {
+    if (value && typeof value === "object" && !Array.isArray(value)) continue;
+    shared[key] = value;
+  }
+  const scoped = harness && plugin[harness] && typeof plugin[harness] === "object"
+    ? plugin[harness]
+    : {};
+
+  return { ...shared, ...scoped };
+}
+
+const REWRITE_MODES = new Set(["off", "client", "server", "auto"]);
+
+/**
+ * Normalize the tri-state rewrite knob.
+ *
+ * off    — never compress
+ * client — always compress locally through the host CLI
+ * server — always ask the server for a digest
+ * auto   — prefer local (cost lands on the user's own subscription), fall back
+ *          to the server when no healthy host CLI is available
+ */
+export function normalizeRewriteMode(value, fallback = "off") {
+  const raw = String(value ?? "").trim().toLowerCase();
+  if (REWRITE_MODES.has(raw)) return raw;
+  if (raw === "1" || raw === "true" || raw === "yes") return "auto";
+  if (raw === "0" || raw === "false" || raw === "no") return "off";
+  return fallback;
+}

package/lib/shared/recall-compress-core.mjs

@@ -0,0 +1,195 @@
+// GENERATED FROM examples/memory-plugin-shared/lib. DO NOT EDIT.
+import { createHash } from "node:crypto";
+import { mkdir, readFile, rename, writeFile } from "node:fs/promises";
+import { dirname } from "node:path";
+
+export const NO_RELEVANT_MEMORY = "NO_RELEVANT_MEMORY";
+export const DIGEST_HEADER = "OpenViking memory digest:";
+const COMPRESS_OK = "ok";
+const COMPRESS_EMPTY = "empty";
+const COMPRESS_FAILED = "failed";
+
+// Medium-constraint prompt: state the goal and two structural floors, but no hard
+// bullet-length contract. Hard per-bullet limits pin the digest to headline
+// density; leaving it unconstrained lets small models rewrite long URIs into dead
+// links, which the URI repair below cleans up.
+export function buildRecallCompressionPrompt({ query, rendered, maxBullets = 6 }) {
+  return `You are a memory relevance compressor utility.
+Do not use any tools. Do not investigate. Only transform the given text.
+
+User query:
+${query}
+
+Retrieved OpenViking context fragments:
+${rendered}
+
+Write a memory digest for a coding agent about to answer that query. Keep the
+concrete facts (paths, identifiers, decisions, constraints); drop pleasantries
+and conversational filler.
+
+Format rules:
+- Group related facts by topic, one bullet per topic, at most ${maxBullets} bullets.
+- Start every bullet with "- ".
+- End every bullet with its source, copied verbatim from the fragments above:
+  "来源：viking://..." or "source: viking://...". Never edit, shorten, or invent a URI.
+- Output the digest body only. No preamble, no closing remark.
+
+If nothing above is relevant to the query, output exactly: ${NO_RELEVANT_MEMORY}`;
+}
+
+function editDistance(a, b) {
+  if (a === b) return 0;
+  const rows = a.length + 1;
+  const cols = b.length + 1;
+  let prev = Array.from({ length: cols }, (_, i) => i);
+  for (let i = 1; i < rows; i += 1) {
+    const cur = [i];
+    for (let j = 1; j < cols; j += 1) {
+      const cost = a[i - 1] === b[j - 1] ? 0 : 1;
+      cur[j] = Math.min(cur[j - 1] + 1, prev[j] + 1, prev[j - 1] + cost);
+    }
+    prev = cur;
+  }
+  return prev[cols - 1];
+}
+
+function nearestUri(candidate, validUris) {
+  let best = "";
+  let bestDistance = Infinity;
+  for (const uri of validUris) {
+    const distance = editDistance(candidate, uri);
+    if (distance < bestDistance) {
+      best = uri;
+      bestDistance = distance;
+    }
+  }
+  // Only repair near-misses; an unrelated hallucination is dropped instead.
+  const tolerance = Math.max(4, Math.floor(candidate.length * 0.25));
+  return bestDistance <= tolerance ? best : "";
+}
+
+/**
+ * Small models occasionally mangle long URIs. Snap every cited URI back onto the
+ * set the server actually returned, and drop bullets whose citation cannot be
+ * recovered so the digest never carries a dead link.
+ */
+export function repairDigestUris(digest, validUris = []) {
+  const text = String(digest || "");
+  if (!text) return "";
+  const valid = validUris.map((uri) => String(uri || "").trim()).filter(Boolean);
+  if (!valid.length) return text;
+  const validSet = new Set(valid);
+
+  const lines = [];
+  for (const line of text.split(/\r?\n/)) {
+    if (!line.trim().startsWith("- ")) {
+      lines.push(line);
+      continue;
+    }
+    let dropped = false;
+    const repaired = line.replace(/viking:\/\/[^\s<>"')\]]+/g, (uri) => {
+      if (validSet.has(uri)) return uri;
+      const nearest = nearestUri(uri, valid);
+      if (nearest) return nearest;
+      dropped = true;
+      return uri;
+    });
+    if (!dropped) lines.push(repaired);
+  }
+  return lines.join("\n").trim();
+}
+
+export function normalizeCompressedContext(raw, maxChars = 4000, maxBullets = 6) {
+  const text = String(raw || "").trim();
+  if (!text) return null;
+  if (text.toUpperCase() === NO_RELEVANT_MEMORY) return "";
+  const bullets = text.split(/\r?\n/)
+    .map((line) => line.trim())
+    .filter((line) => /^[-*]\s+/.test(line) && line.includes("viking://"))
+    .slice(0, Math.max(1, maxBullets))
+    .map((line) => `- ${line.replace(/^[-*]\s+/, "").slice(0, 500).trim()}`);
+  if (!bullets.length) return null;
+  return (`${DIGEST_HEADER}\n${bullets.join("\n")}`).slice(0, Math.max(100, maxChars));
+}
+
+export function recallDigestCacheKey({
+  query = "",
+  rendered = "",
+  entries = [],
+  maxInputChars = 18000,
+  maxBullets = 6,
+} = {}) {
+  const uris = entries.map((entry) => String(entry?.uri || "").trim()).filter(Boolean).sort();
+  const source = JSON.stringify({
+    version: 2,
+    query: String(query),
+    rendered: String(rendered).slice(0, maxInputChars),
+    uris,
+    maxInputChars,
+    maxBullets,
+  });
+  return createHash("sha256").update(source).digest("hex");
+}
+
+async function readCache(path) {
+  if (!path) return null;
+  try { return JSON.parse(await readFile(path, "utf8")); } catch { return null; }
+}
+
+async function writeCache(path, value) {
+  if (!path) return;
+  try {
+    await mkdir(dirname(path), { recursive: true });
+    const tmp = `${path}.tmp`;
+    await writeFile(tmp, JSON.stringify(value));
+    await rename(tmp, path);
+  } catch { /* best effort */ }
+}
+
+export async function compressRecallContext({
+  query,
+  rendered,
+  entries = [],
+  cfg = {},
+  runCompressor,
+  cachePath = "",
+  now = 0,
+}) {
+  const input = String(rendered || "").trim();
+  if (!input) return { status: COMPRESS_EMPTY, context: "" };
+  const minChars = Math.max(0, Number(cfg.recallCompressMinInputChars ?? 1500));
+  if (input.length < minChars) return { status: COMPRESS_OK, context: input };
+
+  const maxInputChars = Math.max(1000, Number(cfg.recallCompressMaxInputChars || 18000));
+  const maxBullets = Math.max(1, Number(cfg.recallCompressMaxBullets || 6));
+  const key = recallDigestCacheKey({
+    query,
+    rendered: input,
+    entries,
+    maxInputChars,
+    maxBullets,
+  });
+  const cached = await readCache(cachePath);
+  if (cached?.key === key && typeof cached.digest === "string") {
+    return { status: COMPRESS_OK, context: cached.digest };
+  }
+
+  const prompt = buildRecallCompressionPrompt({
+    query,
+    rendered: input.slice(0, maxInputChars),
+    maxBullets,
+  });
+  const raw = await runCompressor(prompt);
+  const normalized = normalizeCompressedContext(raw, 4000, maxBullets);
+  if (normalized === null) return { status: COMPRESS_FAILED, context: "" };
+  if (!normalized) return { status: COMPRESS_EMPTY, context: "" };
+
+  const validUris = entries.map((entry) => entry?.uri).filter(Boolean);
+  const digest = repairDigestUris(normalized, validUris.length
+    ? validUris
+    : (input.match(/viking:\/\/[^\s<>"']+/g) || []));
+  if (!digest) return { status: COMPRESS_FAILED, context: "" };
+
+  await writeCache(cachePath, { key, digest, updatedAt: now || 0 });
+  return { status: COMPRESS_OK, context: digest };
+}

package/lib/shared/recall-core.mjs

@@ -1,4 +1,10 @@
 // GENERATED FROM examples/memory-plugin-shared/lib. DO NOT EDIT.
+import { mkdir, readFile, rename, writeFile } from "node:fs/promises";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+
+import { compressRecallContext } from "./recall-compress-core.mjs";
+
 const PREFERENCE_QUERY_RE = /prefer|preference|favorite|favourite|like|偏好|喜欢|爱好|更倾向/i;
 const TEMPORAL_QUERY_RE = /when|what time|date|day|month|year|yesterday|today|tomorrow|last|next|什么时候|何时|哪天|几月|几年|昨天|今天|明天/i;
 const QUERY_TOKEN_RE = /[a-z0-9一-龥]{2,}/gi;
@@ -11,6 +17,17 @@ const SOURCES = [
   { type: "memory", uri: "viking://user/memories", bucket: "memories" },
   { type: "skill", uri: "viking://user/skills", bucket: "skills" },
 ];
+const DEFAULT_CONTEXT_LIMIT = 10;
+const DEFAULT_CONTEXT_MAX_TOKENS = 1600;
+const DEFAULT_REWRITE_MAX_BULLETS = 6;
+const CODING_QUOTA_WEIGHTS = {
+  events: 1,
+  entities: 2,
+  preferences: 1,
+  experiences: 1,
+  resources: 3,
+  skills: 2,
+};
 
 let userSpaceCache = "";
 
@@ -18,16 +35,47 @@ export function estimateTokens(text) {
   return text ? Math.ceil(String(text).length / 4) : 0;
 }
 
+function scaleQuotas(limit, weights) {
+  const slots = Math.max(1, Math.floor(Number(limit) || DEFAULT_CONTEXT_LIMIT));
+  const order = Object.keys(weights);
+  const quotas = Object.fromEntries(order.map((key) => [key, 0]));
+  if (slots < order.length) {
+    for (const key of order) quotas[key] = 1;
+    return quotas;
+  }
+
+  for (const key of order) quotas[key] = 1;
+  const totalWeight = Object.values(weights).reduce((sum, weight) => sum + weight, 0);
+  const ideals = Object.fromEntries(
+    order.map((key) => [key, slots * weights[key] / totalWeight]),
+  );
+  while (order.reduce((sum, key) => sum + quotas[key], 0) < slots) {
+    const key = order.reduce((best, candidate) => (
+      ideals[candidate] - quotas[candidate] > ideals[best] - quotas[best]
+        ? candidate
+        : best
+    ));
+    quotas[key] += 1;
+  }
+  return quotas;
+}
+
+function legacyMemoryQuotas(limit) {
+  return {
+    ...scaleQuotas(limit, { events: 10, entities: 10, preferences: 3 }),
+    experiences: 0,
+  };
+}
+
+function codingQuotas(limit) {
+  return scaleQuotas(limit, CODING_QUOTA_WEIGHTS);
+}
+
 export function buildRecallEndpointBody(cfg = {}) {
-  const limit = Math.max(Number(cfg.recallLimit || 0), 1);
+  const limit = Math.max(Number(cfg.recallLimit || DEFAULT_CONTEXT_LIMIT), 1);
   const body = {
     query: "",
-    quotas: {
-      events: limit,
-      entities: limit,
-      preferences: Math.max(1, Math.min(limit, 3)),
-      experiences: 0,
-    },
+    quotas: legacyMemoryQuotas(limit),
     max_chars: Math.max(Number(cfg.recallMaxContentChars || 0) * limit, 1000),
     min_score: Number.isFinite(Number(cfg.scoreThreshold)) ? Number(cfg.scoreThreshold) : 0.35,
     render: true,
@@ -36,6 +84,106 @@ export function buildRecallEndpointBody(cfg = {}) {
   return body;
 }
 
+/**
+ * Body for the server-side context face. The plugin declares intent (coding
+ * purpose, budget, session) and leaves the mechanics — quota ratios, tier
+ * degradation, cross-turn dedup — to the server's defaults.
+ */
+export function buildContextSearchBody(cfg = {}, options = {}) {
+  const rewriteMode = String(cfg.recallRewrite || "off").toLowerCase();
+  const limit = Math.max(1, Math.floor(Number(cfg.recallLimit || DEFAULT_CONTEXT_LIMIT)));
+  const maxTokens = Math.max(
+    64,
+    Math.floor(Number(cfg.recallMaxTokens || DEFAULT_CONTEXT_MAX_TOKENS)),
+  );
+  const body = {
+    query: "",
+    mode: "context",
+    purpose: "coding",
+    score_threshold: Number.isFinite(Number(cfg.scoreThreshold)) ? Number(cfg.scoreThreshold) : 0.35,
+  };
+  const limitConfigured = cfg.recallLimitConfigured === true;
+  const maxTokensConfigured = cfg.recallMaxTokensConfigured === true;
+  if (limitConfigured) body.quotas = codingQuotas(limit);
+  if (maxTokensConfigured) body.max_tokens = maxTokens;
+  if (cfg.recallPeerScope === "actor") body.peer_scope = "actor";
+
+  const sessionId = String(options.sessionId || "").trim();
+  if (sessionId) {
+    body.session_id = sessionId;
+    const queryExpansionConfigured = cfg.recallQueryExpansionConfigured === true;
+    if (queryExpansionConfigured) {
+      body.query_expansion = cfg.recallQueryExpansion === "off" ? "off" : "auto";
+    }
+    const dedupTurns = Number(cfg.recallDedupTurns);
+    const resolvedDedupTurns = Number.isFinite(dedupTurns)
+      ? Math.max(0, Math.floor(dedupTurns))
+      : 5;
+    if (resolvedDedupTurns > 0) body.dedup_turns = resolvedDedupTurns;
+  }
+
+  const excludeUris = Array.isArray(options.excludeUris) ? options.excludeUris.slice(0, 200) : [];
+  if (excludeUris.length) body.exclude_uris = excludeUris;
+
+  if (rewriteMode === "server") body.rewrite = true;
+  else if (rewriteMode === "auto" && !options.localCompressorAvailable) body.rewrite = "auto";
+  const rewriteMaxBullets = Math.max(
+    1,
+    Math.floor(Number(cfg.recallCompressMaxBullets || DEFAULT_REWRITE_MAX_BULLETS)),
+  );
+  const rewriteMaxBulletsConfigured = cfg.recallCompressMaxBulletsConfigured === true;
+  if (body.rewrite !== undefined && rewriteMaxBulletsConfigured) {
+    body.rewrite_max_bullets = rewriteMaxBullets;
+  }
+  return body;
+}
+
+// The server pipeline is serial and each optional stage has its own fuse. A
+// request is aborted client-side unless its deadline covers every stage it
+// asked for, and aborting discards the whole response rather than just the
+// stage that ran long.
+//
+//   session_id  -> query expansion   (retrieval.recall_intent_timeout_s,  5s)
+//   always      -> retrieval, body reads, budget planning
+//   rewrite     -> digest            (retrieval.recall_rewrite_timeout_s, 30s)
+//
+// Both budgets stay inside the 60s prompt-hook allowance, the rewrite one with
+// a quarter to spare.
+const EXPANSION_REQUEST_TIMEOUT_MS = 15000;
+const SERVER_REWRITE_REQUEST_TIMEOUT_MS = 45000;
+
+/**
+ * HTTP deadline for one context request, or undefined to keep the caller's own.
+ *
+ * Derived from the request body, because the body is what states which server
+ * stages will run: reading `cfg` alone cannot tell a bare retrieval from one
+ * that also spends the expansion or rewrite fuse.
+ */
+export function contextRequestTimeoutMs(cfg = {}, body = {}) {
+  const wantsRewrite = body.rewrite !== undefined;
+  // `query_expansion` defaults to "auto" server-side, so only an explicit "off"
+  // takes the expansion fuse back out of the budget.
+  const wantsExpansion = Boolean(body.session_id) && body.query_expansion !== "off";
+  if (!wantsRewrite && !wantsExpansion) return undefined;
+
+  const configured = Number(cfg.recallContextTimeoutMs);
+  if (Number.isFinite(configured) && configured > 0) return Math.max(1000, Math.floor(configured));
+  const floor = wantsRewrite ? SERVER_REWRITE_REQUEST_TIMEOUT_MS : EXPANSION_REQUEST_TIMEOUT_MS;
+  return Math.max(Number(cfg.timeoutMs) || 0, floor);
+}
+
+/**
+ * Strip the context-face fields a pre-context server rejects, converting the
+ * token budget back to v1's character budget.
+ */
+export function downgradeToRecallBody(contextBody = {}, cfg = {}) {
+  const body = buildRecallEndpointBody(cfg);
+  body.query = contextBody.query || "";
+  body.max_chars = Math.max(1000, Math.floor(Number(contextBody.max_tokens || 1600) * 4));
+  if (contextBody.peer_scope) body.peer_scope = contextBody.peer_scope;
+  return body;
+}
+
 function clampScore(v) {
   if (typeof v !== "number" || Number.isNaN(v)) return 0;
   return Math.max(0, Math.min(1, v));
@@ -232,6 +380,164 @@ async function buildFallbackInjectionBlock(fetchJSON, items, cfg, actorPeerId =
   return lines.join("\n");
 }
 
+const LEGACY_CACHE_TTL_MS = 6 * 60 * 60 * 1000;
+
+function stateFile(name) {
+  const override = String(process.env.OPENVIKING_STATE_DIR || "").trim();
+  return override ? join(override, name) : join(homedir(), ".openviking", "state", name);
+}
+
+async function readJsonFile(path) {
+  try { return JSON.parse(await readFile(path, "utf8")); } catch { return null; }
+}
+
+async function writeJsonFile(path, value) {
+  try {
+    await mkdir(dirname(path), { recursive: true });
+    const tmp = `${path}.tmp`;
+    await writeFile(tmp, JSON.stringify(value));
+    await rename(tmp, path);
+  } catch { /* best effort */ }
+}
+
+/**
+ * Hooks are one-shot processes, so "this server has no context face" has to be
+ * remembered on disk or every turn pays for a rejected request.
+ */
+export async function isContextFaceLegacy(path = stateFile("context-face.json"), now = Date.now()) {
+  const cached = await readJsonFile(path);
+  return Boolean(cached?.legacyUntil && Number(cached.legacyUntil) > now);
+}
+
+export async function markContextFaceLegacy(path = stateFile("context-face.json"), now = Date.now()) {
+  await writeJsonFile(path, { legacyUntil: now + LEGACY_CACHE_TTL_MS });
+}
+
+function looksLikeUnknownField(res) {
+  const text = JSON.stringify(res?.error ?? res?.result ?? res?.detail ?? "").toLowerCase();
+  return text.includes("extra") || text.includes("mode") || text.includes("unexpected");
+}
+
+function wrapContext(body) {
+  return [
+    "<openviking-context>",
+    "Relevant memory from OpenViking. Use the recall/read MCP tools to expand URIs.",
+    body,
+    "</openviking-context>",
+  ].join("\n");
+}
+
+/**
+ * Server-assembled context: the context face when the deployment has it, else
+ * the deprecated /recall preset. Returns the injection block, "" when there was
+ * nothing relevant, or null when no server-side path was usable at all.
+ */
+export async function buildServerAssembledBlock(fetchJSON, cfg, query, options = {}) {
+  const actorPeerId = options.actorPeerId ?? cfg.peerId ?? "";
+  const log = options.log || (() => {});
+
+  const block = await recallViaContextFace(fetchJSON, cfg, query, { ...options, actorPeerId }, log);
+  if (block !== null) return block;
+  return recallViaEndpoint(fetchJSON, cfg, query, actorPeerId, log);
+}
+
+/**
+ * Raw server-assembled context, or null when the deployment has no context face.
+ * Returns `{ rendered, entries, digest, stats }` — callers that need the entries
+ * (their own compression, their own envelope) use this instead of the block
+ * builders below.
+ */
+export async function fetchAssembledContext(fetchJSON, cfg, query, options = {}) {
+  const actorPeerId = options.actorPeerId || "";
+  const log = options.log || (() => {});
+  if (await isContextFaceLegacy(options.legacyCachePath)) return null;
+
+  const body = buildContextSearchBody(cfg, options);
+  body.query = query;
+  const res = await fetchJSON("/api/v1/search/search", {
+    method: "POST",
+    body: JSON.stringify(body),
+  }, { actorPeerId, timeoutMs: contextRequestTimeoutMs(cfg, body) });
+
+  if (!res.ok) {
+    const status = res.status || 0;
+    if ((status === 400 || status === 422) && looksLikeUnknownField(res)) {
+      await markContextFaceLegacy(options.legacyCachePath);
+      log("recall_context_face_unsupported", { status });
+    } else {
+      log("recall_context_face_error", { status });
+    }
+    return null;
+  }
+
+  const result = res.result || {};
+  const stats = result.stats || {};
+  log("recall_context_assembled", {
+    entries: Array.isArray(result.entries) ? result.entries.length : 0,
+    usedTokens: stats.used_tokens || 0,
+    tiers: stats.tier_counts || {},
+    rewrite: stats.rewrite || "off",
+  });
+  return {
+    rendered: String(result.rendered || "").trim(),
+    entries: Array.isArray(result.entries) ? result.entries : [],
+    digest: String(result.digest || "").trim(),
+    stats,
+  };
+}
+
+/**
+ * Entry field compatibility: the context face returns `category`/`text`, while
+ * the deprecated /recall v1 shape used `type` plus `content`/`summary`.
+ */
+export function normalizeContextEntry(entry = {}) {
+  return {
+    uri: String(entry.uri || "").trim(),
+    category: String(entry.category || entry.type || "memory").trim() || "memory",
+    detail: String(entry.detail || entry.mode || "").trim(),
+    score: Number(entry.score) || 0,
+    text: String(
+      entry.text || entry.content || entry.summary || entry.abstract || entry.uri || "",
+    ).trim(),
+  };
+}
+
+async function recallViaContextFace(fetchJSON, cfg, query, options, log) {
+  const assembled = await fetchAssembledContext(fetchJSON, cfg, query, { ...options, log });
+  if (assembled === null) return null;
+
+  const { rendered, entries } = assembled;
+  let digest = assembled.digest;
+  const mode = String(cfg.recallRewrite || "off").toLowerCase();
+  if (String(assembled.stats?.rewrite || "").toLowerCase() === "no_relevant") {
+    log("recall_server_compression", { status: "empty" });
+    return "";
+  }
+  const wantsLocal = mode === "client" || (mode === "auto" && !digest);
+  if (wantsLocal && rendered && typeof options.runCompressor === "function") {
+    try {
+      const compression = await compressRecallContext({
+        query,
+        rendered,
+        entries,
+        cfg,
+        runCompressor: options.runCompressor,
+        cachePath: options.digestCachePath || stateFile("recall-digest.json"),
+        now: Date.now(),
+      });
+      log("recall_local_compression", { status: compression.status });
+      if (compression.status === "ok") digest = compression.context;
+      if (compression.status === "empty") return "";
+    } catch (err) {
+      log("recall_local_compression_failed", { error: String(err?.message || err) });
+    }
+  }
+
+  const injected = digest || rendered;
+  if (!injected) return "";
+  return wrapContext(injected);
+}
+
 async function recallViaEndpoint(fetchJSON, cfg, query, actorPeerId = "", log = () => {}) {
   const body = buildRecallEndpointBody(cfg);
   body.query = query;
@@ -242,12 +548,7 @@ async function recallViaEndpoint(fetchJSON, cfg, query, actorPeerId = "", log =
   }
   const rendered = String(res.result?.rendered || "").trim();
   if (!rendered) return "";
-  return [
-    "<openviking-context>",
-    "Relevant memory from OpenViking. Use the recall/read MCP tools to expand URIs.",
-    rendered,
-    "</openviking-context>",
-  ].join("\n");
+  return wrapContext(rendered);
 }
 
 export async function postRecall(fetchJSON, body, opts = {}) {
@@ -277,10 +578,16 @@ export async function buildRecallBlock(fetchJSON, cfg, query, options = {}) {
   const trimmed = String(query || "").trim();
   if (!trimmed) return null;
 
-  const endpointBlock = await recallViaEndpoint(fetchJSON, cfg, trimmed, actorPeerId, log);
-  if (endpointBlock !== null) return endpointBlock || null;
+  // Assembly happens server-side when the deployment offers the context face;
+  // older servers fall through to /recall, then to raw find.
+  const serverBlock = await buildServerAssembledBlock(fetchJSON, cfg, trimmed, {
+    ...options,
+    actorPeerId,
+    log,
+  });
+  if (serverBlock !== null) return serverBlock || null;
 
-  const recallLimit = Math.max(1, Number(cfg.recallLimit || 6));
+  const recallLimit = Math.max(1, Number(cfg.recallLimit || DEFAULT_CONTEXT_LIMIT));
   const perSourceLimit = Math.max(recallLimit * 2, 8);
   const raw = await searchAllSources(fetchJSON, trimmed, perSourceLimit, actorPeerId, log);
   if (raw.length === 0) return null;

package/lib/shared/retryable.mjs

@@ -0,0 +1,9 @@
+// GENERATED FROM examples/memory-plugin-shared/lib. DO NOT EDIT.
+export function isRetryableFailure(result) {
+  if (!result || result.ok) return false;
+  const status = Number(result.status || 0);
+  if (!status || status === 408 || status === 429 || status >= 500) {
+    return true;
+  }
+  return status === 409 && result.error?.details?.retryable === true;
+}

package/lib/utils.mjs

@@ -213,6 +213,7 @@ function makeAuthHeaders(config, headers = {}, actorPeerId = "") {
   if (config.user) result["X-OpenViking-User"] = config.user
   const peerId = String(actorPeerId || "").trim()
   if (peerId) result["X-OpenViking-Actor-Peer"] = peerId
+  if (config.userAgent) result["User-Agent"] = config.userAgent
   return result
 }
 

package/lib/viking-uri-guard.mjs

@@ -4,7 +4,7 @@ import { buildGuardMessage, findVikingUri, normalizeToolName } from "./shared/ur
 const FILESYSTEM_TOOL_HINTS = {
   read: {
     tool: "openviking_read",
-    example: (uri) => `openviking_read(uri="${uri}")`,
+    example: (uri) => `openviking_read(uris=["${uri}"])`,
   },
   glob: {
     tool: "openviking_glob",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openviking/opencode-plugin",
-  "version": "0.2.3",
+  "version": "0.2.4",
   "author": "@openviking",
   "description": "Unified OpenCode plugin for OpenViking repository retrieval and long-term memory",
   "type": "module",

package/servers/mcp-proxy.mjs

@@ -46,6 +46,7 @@ function readProxyConfig() {
     account: cfg.account || "",
     user: cfg.user || "",
     peerId: effectivePeer.peerId,
+    userAgent: cfg.userAgent || "",
     timeoutMs: Math.max(1000, Number(cfg.timeoutMs) || DEFAULT_TIMEOUT_MS),
     debug: cfg.debug === true,
     debugLogPath: cfg.debugLogPath,

package/servers/mcp-proxy.test.mjs

@@ -56,6 +56,7 @@ function makeProxy(url) {
       account: "acct",
       user: "user",
       peerId: "peer",
+      userAgent: "openviking-memory-opencode/9.9.9",
       timeoutMs: 5000,
       debug: false,
       debugLogPath: "",
@@ -81,6 +82,7 @@ test("OpenCode MCP proxy forwards initialize with auth and identity headers", as
     assert.equal(entry.headers["x-openviking-account"], "acct")
     assert.equal(entry.headers["x-openviking-user"], "user")
     assert.equal(entry.headers["x-openviking-actor-peer"], "peer")
+    assert.equal(entry.headers["user-agent"], "openviking-memory-opencode/9.9.9")
     res.writeHead(200, {
       "content-type": "text/event-stream",
       "mcp-session-id": "sid-oc",