@openviking/openclaw-plugin 2026.9.1 → 2026.9.4-1

package/dist/client.js

@@ -7,6 +7,7 @@ import { basename, dirname, join, relative } from "node:path";
 import { Zip, ZipDeflate } from "fflate";
 import { defaultHttpTransport } from "./adapters/http-transport.js";
 import { defaultResourcePackager, } from "./adapters/resource-packager.js";
+import { buildContextSearchBody, contextRequestTimeoutMs, normalizeContextEntry, } from "./shared/recall-core.mjs";
 function userSessionUri(sessionId) {
     return `viking://~/sessions/${encodeURIComponent(sessionId)}`;
 }
@@ -215,6 +216,59 @@ export class OpenVikingClient {
             body: JSON.stringify(body),
         }, undefined, actorPeerId);
     }
+    async searchContext(query, options = {}) {
+        const contractConfig = {
+            recallLimit: options.limit,
+            recallLimitConfigured: options.limit !== undefined,
+            recallMaxTokens: options.maxTokens,
+            recallMaxTokensConfigured: options.maxTokens !== undefined,
+            scoreThreshold: options.scoreThreshold,
+            recallQueryExpansion: options.queryExpansion,
+            recallQueryExpansionConfigured: options.queryExpansion !== undefined,
+            recallDedupTurns: options.dedupTurns,
+            recallPeerScope: options.peerScope,
+            recallContextTimeoutMs: options.requestTimeoutMs,
+            timeoutMs: this.timeoutMs,
+        };
+        const body = {
+            ...buildContextSearchBody(contractConfig, { sessionId: options.sessionId }),
+            query,
+            ...(options.contextType !== undefined ? { context_type: options.contextType } : {}),
+            ...(options.detail !== undefined ? { detail: options.detail } : {}),
+        };
+        const requestTimeoutMs = contextRequestTimeoutMs(contractConfig, body);
+        const actorPeerId = this.resolveActorPeerHeader(options.actorPeerId);
+        const tenantHeaders = this.resolveTenantHeaders();
+        this.routingDebugLog?.(`openviking: context search POST ${this.baseUrl}/api/v1/search/search ` +
+            JSON.stringify({
+                X_OpenViking_Account: tenantHeaders.accountId ?? null,
+                X_OpenViking_User: tenantHeaders.userId ?? null,
+                X_OpenViking_Actor_Peer: actorPeerId ?? null,
+                session_id: body.session_id ?? null,
+                query: query.length > 4000
+                    ? `${query.slice(0, 4000)}…(+${query.length - 4000} more chars)`
+                    : query,
+                purpose: body.purpose,
+                quotas: body.quotas ?? null,
+                score_threshold: body.score_threshold,
+                context_type: body.context_type ?? null,
+                query_expansion: body.query_expansion ?? null,
+                max_tokens: body.max_tokens ?? null,
+                detail: body.detail ?? null,
+                dedup_turns: body.dedup_turns ?? 0,
+                peer_scope: body.peer_scope ?? null,
+            }));
+        const result = await this.request("/api/v1/search/search", {
+            method: "POST",
+            body: JSON.stringify(body),
+        }, requestTimeoutMs, actorPeerId);
+        return {
+            ...result,
+            entries: Array.isArray(result.entries)
+                ? result.entries.map((entry) => ({ ...entry, ...normalizeContextEntry(entry) }))
+                : result.entries,
+        };
+    }
     async read(uri, actorPeerId) {
         return this.request(`/api/v1/content/read?uri=${encodeURIComponent(uri)}`, {}, undefined, actorPeerId);
     }

package/dist/commands/setup.js

@@ -76,7 +76,7 @@ const CONFIG_KEYS_TO_PRESERVE = [
     "emitStandardDiagnostics",
     "logFindRequests",
 ];
-const DEFAULT_SETUP_PEER_ROLE = "assistant";
+const DEFAULT_SETUP_PEER_ROLE = "none";
 const ALLOWED_RECALL_TARGET_TYPES = ["resource", "user", "agent"];
 function tr(langZh, en, zh) {
     return langZh ? zh : en;
@@ -98,7 +98,9 @@ function normalizePeerRole(value) {
     if (typeof value !== "string")
         return undefined;
     const role = value.trim().toLowerCase();
-    if (role === "none" || role === "assistant" || role === "person")
+    if (role === "person")
+        return "sender";
+    if (role === "none" || role === "assistant" || role === "sender")
         return role;
     return undefined;
 }
@@ -121,7 +123,7 @@ function resolveSetupPeerRole(value) {
     const role = normalizePeerRole(value);
     if (role)
         return role;
-    throw new Error('peer_role must be "none", "assistant", or "person"');
+    throw new Error('peer_role must be "none", "assistant", or "sender" (legacy alias: "person")');
 }
 function normalizeSetupRecallTargetTypes(value) {
     if (value === undefined || value === null || value === "") {
@@ -172,12 +174,17 @@ function preserveCurrentConfig(existing) {
     return config;
 }
 async function askPeerRole(zh, q, defaultValue) {
+    console.log(`  ${tr(zh, "Memory scope — none (default): viking://user/<user_id>/memories, shared across all conversations; " +
+        "assistant: viking://user/<user_id>/peers/<assistant_id>/memories; " +
+        "sender: viking://user/<user_id>/peers/<sender_id>/memories (legacy alias: person).", "记忆归属 —— none（默认）：viking://user/<user_id>/memories，所有对话共享；" +
+        "assistant：viking://user/<user_id>/peers/<assistant_id>/memories；" +
+        "sender：viking://user/<user_id>/peers/<sender_id>/memories（兼容旧值 person）。")}`);
     while (true) {
-        const value = await q(tr(zh, "Peer Role (none/assistant/person)", "Peer Role（none/assistant/person）"), defaultValue);
+        const value = await q(tr(zh, "Memory scope (none/assistant/sender)", "记忆归属（none/assistant/sender）"), defaultValue);
         const role = normalizePeerRole(value);
         if (role)
             return role;
-        console.log(`  ✗ ${tr(zh, 'Peer Role must be "none", "assistant", or "person".', 'Peer Role 必须是 "none"、"assistant" 或 "person"。')}`);
+        console.log(`  ✗ ${tr(zh, 'Memory scope must be "none", "assistant", or "sender" (legacy "person" is also accepted).', '记忆归属必须是 "none"、"assistant" 或 "sender"（也兼容旧值 "person"）。')}`);
     }
 }
 async function askPeerPrefix(zh, q, defaultValue) {
@@ -473,7 +480,7 @@ export function registerSetupCli(api) {
             .option("--zh", "Chinese prompts")
             .option("--base-url <url>", "OpenViking server URL (enables non-interactive mode)")
             .option("--api-key <key>", "API key for authentication")
-            .option("--peer-role <role>", "Peer ID role: none, assistant, or person")
+            .option("--peer-role <role>", "Memory scope: none (shared), assistant (per assistant), or sender (per sender); person is a legacy alias")
             .option("--peer-prefix <prefix>", "Prefix for assistant peer_id values")
             .option("--account-id <id>", "Account ID (required for root API keys)")
             .option("--user-id <id>", "User ID (required for root API keys)")
@@ -952,6 +959,8 @@ async function setupRemote(zh, configPath, existing, q) {
 export const __test__ = {
     isLegacyLocalMode,
     isValidPeerPrefixInput,
+    normalizePeerRole,
+    resolveSetupPeerRole,
     normalizeSetupRecallTargetTypes,
     activateContextEngineSlot,
     isContextEngineSlotActive,

package/dist/config.js

@@ -6,7 +6,9 @@ const DEFAULT_TARGET_URI = "viking://~/memories";
 const DEFAULT_TIMEOUT_MS = 15000;
 const DEFAULT_CAPTURE_MODE = "semantic";
 const DEFAULT_CAPTURE_MAX_LENGTH = 24000;
-const DEFAULT_AUTO_RECALL_TIMEOUT_MS = 5000;
+// Session-aware context search may spend up to 5 seconds on query expansion
+// before returning its server-side fallback, so leave headroom for retrieval.
+const DEFAULT_AUTO_RECALL_TIMEOUT_MS = 15000;
 const DEFAULT_RECALL_LIMIT = 6;
 const DEFAULT_RECALL_SCORE_THRESHOLD = 0.15;
 const DEFAULT_RECALL_MAX_CONTENT_CHARS = 5000;
@@ -16,7 +18,7 @@ const DEFAULT_COMMIT_TOKEN_THRESHOLD_RATIO = 0.5;
 const DEFAULT_COMMIT_KEEP_RECENT_COUNT = 10;
 const DEFAULT_BYPASS_SESSION_PATTERNS = [];
 const DEFAULT_EMIT_STANDARD_DIAGNOSTICS = false;
-const DEFAULT_PEER_ROLE = "assistant";
+const DEFAULT_PEER_ROLE = "none";
 const DEFAULT_PEER_PREFIX = "";
 const DEFAULT_TRACE_RECALL_DIR = "~/.openclaw/openviking/recall-traces";
 const DEFAULT_TRACE_RECALL_RETENTION_DAYS = 14;
@@ -142,13 +144,16 @@ function resolveSecret(value, label) {
 function resolvePeerRole(configured) {
     if (typeof configured === "string") {
         const role = configured.trim().toLowerCase();
-        if (role === "none" || role === "assistant" || role === "person") {
+        if (role === "none" || role === "assistant" || role === "sender") {
             return role;
         }
-        throw new Error(`openviking peer_role must be "none", "assistant", or "person"`);
+        if (role === "person") {
+            return "sender";
+        }
+        throw new Error(`openviking peer_role must be "none", "assistant", or "sender" (legacy alias: "person")`);
     }
     if (configured !== undefined) {
-        throw new Error(`openviking peer_role must be "none", "assistant", or "person"`);
+        throw new Error(`openviking peer_role must be "none", "assistant", or "sender" (legacy alias: "person")`);
     }
     return DEFAULT_PEER_ROLE;
 }
@@ -479,14 +484,16 @@ export const memoryOpenVikingConfigSchema = {
             help: "HTTP URL when mode is remote (or use ${OPENVIKING_BASE_URL})",
         },
         peer_role: {
-            label: "Peer Role",
+            label: "Memory Scope (peer_role)",
             placeholder: DEFAULT_PEER_ROLE,
-            help: 'Controls which session messages get peer_id: "none", "assistant", or "person".',
+            help: 'Where peer-scoped memories are stored. "none" (default): viking://user/<user_id>/memories. ' +
+                '"assistant": viking://user/<user_id>/peers/<assistant_id>/memories. ' +
+                '"sender": viking://user/<user_id>/peers/<sender_id>/memories. Legacy "person" is accepted as "sender".',
         },
         peer_prefix: {
             label: "Peer Prefix",
             placeholder: "optional-prefix",
-            help: "Optional prefix applied to assistant peer_id values derived from OpenClaw runtime agent IDs.",
+            help: 'Only used when Memory Scope is "assistant". Prefix added to the peer id derived from the OpenClaw agent id.',
         },
         apiKey: {
             label: "OpenViking API Key",
@@ -547,7 +554,7 @@ export const memoryOpenVikingConfigSchema = {
             label: "Auto-Recall Timeout (ms)",
             placeholder: String(DEFAULT_AUTO_RECALL_TIMEOUT_MS),
             advanced: true,
-            help: "Outer time budget for the whole auto-recall flow, including search, ranking, and memory reads.",
+            help: "Outer time budget for the server-assembled context search, including session-aware query expansion.",
         },
         recallResources: {
             label: "Recall Resources",
@@ -574,7 +581,7 @@ export const memoryOpenVikingConfigSchema = {
             label: "Recall Max Injected Chars",
             placeholder: String(DEFAULT_RECALL_MAX_INJECTED_CHARS),
             advanced: true,
-            help: "Maximum total characters for auto-recall memory injection. Complete memories that do not fit are skipped, not truncated.",
+            help: "Legacy auto-recall character budget. It is converted to the server context token budget at four characters per token.",
         },
         recallMaxContentChars: {
             label: "Deprecated Recall Max Content Chars",
@@ -585,7 +592,7 @@ export const memoryOpenVikingConfigSchema = {
         recallPreferAbstract: {
             label: "Recall Prefer Abstract",
             advanced: true,
-            help: "Use memory abstract instead of fetching full content when abstract is available. Reduces token usage.",
+            help: "Pin server-assembled auto-recall entries to abstract detail. When disabled, the server chooses each category's default detail tier.",
         },
         recallTokenBudget: {
             label: "Deprecated Recall Token Budget",

package/dist/plugin/openviking-memory-tools.js

@@ -45,7 +45,7 @@ export function registerOpenVikingMemoryTools(deps) {
                 const peerId = resolveOpenVikingMessagePeerId({
                     peerRole: deps.peerRole,
                     role,
-                    personPeerId: session.actorPeerId,
+                    senderPeerId: session.actorPeerId,
                     assistantPeerId: session.actorPeerId,
                 });
                 await client.addSessionMessage(sessionId, role, [{ type: "text", text }], undefined, undefined, peerId);

package/dist/plugin/openviking-session-routing-runtime.js

@@ -1,6 +1,6 @@
 import { createSessionAgentResolver, openClawSessionToOvStorageId, resolveOpenVikingActorPeerId, sanitizeOpenVikingPeerId, } from "../routing/identity-routing.js";
 export function createOpenVikingSessionRoutingRuntime(options) {
-    const peerRole = options.peerRole ?? "assistant";
+    const peerRole = options.peerRole ?? "none";
     const sessionAgentResolver = createSessionAgentResolver(options.peerPrefix);
     const rememberSessionAgentId = (ctx) => {
         sessionAgentResolver.remember(ctx);
@@ -48,7 +48,7 @@ export function createOpenVikingSessionRoutingRuntime(options) {
             agentId,
             actorPeerId: resolveOpenVikingActorPeerId({
                 peerRole,
-                personPeerId: sanitizeOpenVikingPeerId(ctx?.requesterSenderId ?? ctx?.senderId),
+                senderPeerId: sanitizeOpenVikingPeerId(ctx?.requesterSenderId ?? ctx?.senderId),
                 assistantPeerId: agentId,
             }),
         };

package/dist/routing/identity-routing.js

@@ -12,8 +12,8 @@ export function sanitizeOpenVikingPeerId(raw) {
     return normalized || undefined;
 }
 export function resolveOpenVikingMessagePeerId(params) {
-    if (params.peerRole === "person" && params.role === "user") {
-        return params.personPeerId;
+    if (params.peerRole === "sender" && params.role === "user") {
+        return params.senderPeerId;
     }
     if (params.peerRole === "assistant" && params.role === "assistant") {
         return params.assistantPeerId;
@@ -23,10 +23,10 @@ export function resolveOpenVikingMessagePeerId(params) {
 export function resolveOpenVikingActorPeerId(params) {
     const actorPeerId = resolveOpenVikingMessagePeerId({
         ...params,
-        role: params.peerRole === "person" ? "user" : "assistant",
+        role: params.peerRole === "sender" ? "user" : "assistant",
     });
-    if (params.peerRole === "person" && !actorPeerId) {
-        throw new Error("openviking: peer_role=person requires a sender identity");
+    if (params.peerRole === "sender" && !actorPeerId) {
+        throw new Error("openviking: peer_role=sender requires a sender identity");
     }
     return actorPeerId;
 }

package/dist/services/context-lifecycle-service.js

@@ -243,8 +243,8 @@ export async function assembleOpenVikingSession({ sessionId, sessionKey, message
             const routingRef = sessionId ?? sessionKey ?? ovSessionId;
             const agentId = resolveAgentId(routingRef, sessionKey, ovSessionId);
             const actorPeerId = resolveOpenVikingActorPeerId({
-                peerRole: cfg.peer_role ?? "assistant",
-                personPeerId: sanitizeOpenVikingPeerId(sender.senderId),
+                peerRole: cfg.peer_role ?? "none",
+                senderPeerId: sanitizeOpenVikingPeerId(sender.senderId),
                 assistantPeerId: agentId,
             });
             const queryConfig = await queryConfigStore?.getEffective({
@@ -595,9 +595,9 @@ export async function afterTurnOpenVikingSession({ sessionId, sessionKey, messag
             });
             if (ovParts.length > 0) {
                 await client.addSessionMessage(ovSessionId, msg.role, ovParts, undefined, createdAt, resolveOpenVikingMessagePeerId({
-                    peerRole: cfg.peer_role ?? "assistant",
+                    peerRole: cfg.peer_role ?? "none",
                     role: msg.role,
-                    personPeerId: senderRoleId,
+                    senderPeerId: senderRoleId,
                     assistantPeerId: agentId,
                 }));
             }

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

@@ -0,0 +1,188 @@
+// 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 };
+}