@openviking/openclaw-plugin 2026.10.6 → 2026.10.7

package/README.md

@@ -1,5 +1,7 @@
 # OpenViking for OpenClaw
 
+> **Working memory is now opt-in.** Update installed plugins separately from the OV server, then restart the host. Existing explicit settings still take precedence. See the [default-off upgrade guide](../../docs/en/guides/working-memory-default-off.md) for native history, re-enabling WM, and old-conversation handoffs.
+
 Use [OpenViking](https://github.com/volcengine/OpenViking) as OpenClaw's long-term context engine: automatic recall, session archive, memory extraction, semantic search, and RAG over a remote OpenViking server.
 
 ## Quick Start
@@ -243,7 +245,7 @@ Use it as a complement to auto-capture, not a replacement:
 
 - auto-capture still preserves ordinary conversation flow and batches extraction for cost and latency
 - `memory_store` is for explicit durable-memory intent such as "remember my main project is X" or "save this preference"
-- if `memory_store` commits but extracts 0 memories, check the OpenViking server extraction/model configuration; the explicit path triggered extraction, but the extractor did not produce a memory
+- if `memory_store` commits but extracts 0 memories, it returns `action: "failed"` with `error: "no_memories_extracted"` and the agent tells the user no new memory was created; possible causes are that the content is already stored, extraction is disabled, or the extraction/model configuration needs checking
 
 ### What `compact()` does
 

package/client.ts

@@ -75,6 +75,7 @@ export type OpenVikingClientOptions = {
 };
 
 export type CommitSessionResult = {
+  effective_enable_working_memory?: boolean;
   session_id: string;
   /** "accepted" (async), "skipped" (no archive), "completed", "failed", or "timeout" (wait mode). */
   status: string;
@@ -841,6 +842,7 @@ export class OpenVikingClient {
     sessionId: string,
     options?: {
       wait?: boolean;
+      enableWorkingMemory?: boolean;
       timeoutMs?: number;
       /**
        * WM v2: number of most-recent messages to keep live after commit.
@@ -871,6 +873,9 @@ export class OpenVikingClient {
       options?.agentId,
     );
     const body: Record<string, unknown> = {};
+    if (options?.enableWorkingMemory !== undefined) {
+      body.enable_working_memory = options.enableWorkingMemory;
+    }
     if (options?.retentionMode === "turn_budget") {
       body.retention_mode = "turn_budget";
     } else if (keepRecentCount > 0) {

package/commands/setup.ts

@@ -66,6 +66,7 @@ function readCompatRangeFromManifest(): { min: string; max: string } {
 const PLUGIN_VERSION = readPluginVersion();
 const { min: COMPATIBLE_SERVER_MIN, max: COMPATIBLE_SERVER_MAX } = readCompatRangeFromManifest();
 const CONFIG_KEYS_TO_PRESERVE = [
+  "contextManagementMode",
   "targetUri",
   "headers",
   "timeoutMs",

package/config.ts

@@ -42,6 +42,7 @@ export type MemoryOpenVikingConfig = {
   userId?: string;
   targetUri?: string;
   timeoutMs?: number;
+  contextManagementMode?: "native" | "openviking";
   autoCapture?: boolean;
   captureMode?: "semantic" | "keyword";
   captureMaxLength?: number;
@@ -514,6 +515,9 @@ export const memoryOpenVikingConfigSchema = {
       value = {};
     }
     const cfg = value as Record<string, unknown>;
+    if (cfg.contextManagementMode !== undefined && !["native", "openviking"].includes(String(cfg.contextManagementMode))) {
+      throw new Error("contextManagementMode must be native or openviking");
+    }
     assertAllowedKeys(
       cfg,
       [
@@ -528,6 +532,7 @@ export const memoryOpenVikingConfigSchema = {
         "userId",
         "targetUri",
         "timeoutMs",
+        "contextManagementMode",
         "autoCapture",
         "captureMode",
         "captureMaxLength",
@@ -655,6 +660,7 @@ export const memoryOpenVikingConfigSchema = {
       userId,
       targetUri: typeof cfg.targetUri === "string" ? cfg.targetUri : DEFAULT_TARGET_URI,
       timeoutMs: Math.max(1000, Math.floor(toNumber(cfg.timeoutMs, DEFAULT_TIMEOUT_MS))),
+      contextManagementMode: cfg.contextManagementMode === "openviking" ? "openviking" : "native",
       autoCapture: cfg.autoCapture !== false,
       captureMode: captureMode ?? DEFAULT_CAPTURE_MODE,
       captureMaxLength: Math.max(

package/context-engine.ts

@@ -25,7 +25,7 @@ type ContextEngineInfo = {
   id: string;
   name: string;
   version?: string;
-  ownsCompaction: true;
+  ownsCompaction: boolean;
   /** OpenClaw >=2026.8.1: without both declarations (and commitTurn) the engine is degraded to "legacy" every turn. */
   transcriptSemantics: {
     currentTurnFence: "before-current-turn-entry-v1";
@@ -365,7 +365,7 @@ export function createMemoryOpenVikingContextEngine(params: {
       id,
       name,
       version,
-      ownsCompaction: true,
+      ownsCompaction: cfg.contextManagementMode === "openviking",
       transcriptSemantics: {
         currentTurnFence: "before-current-turn-entry-v1",
         turnAdvancementIdempotency: "atomic-idempotent-v1",
@@ -490,6 +490,7 @@ export function createMemoryOpenVikingContextEngine(params: {
     async compact(compactParams): Promise<CompactResult> {
       const tokenBudget = validTokenBudget(compactParams.tokenBudget) ?? 128_000;
       return compactOpenVikingSession({
+        contextManagementMode: cfg.contextManagementMode,
         sessionId: compactParams.sessionId,
         sessionKey: resolveSessionKey(compactParams),
         tokenBudget,

package/dist/client.js

@@ -414,6 +414,9 @@ export class OpenVikingClient {
             retentionMode: options?.retentionMode,
         }, options?.agentId);
         const body = {};
+        if (options?.enableWorkingMemory !== undefined) {
+            body.enable_working_memory = options.enableWorkingMemory;
+        }
         if (options?.retentionMode === "turn_budget") {
             body.retention_mode = "turn_budget";
         }

package/dist/commands/setup.js

@@ -56,6 +56,7 @@ function readCompatRangeFromManifest() {
 const PLUGIN_VERSION = readPluginVersion();
 const { min: COMPATIBLE_SERVER_MIN, max: COMPATIBLE_SERVER_MAX } = readCompatRangeFromManifest();
 const CONFIG_KEYS_TO_PRESERVE = [
+    "contextManagementMode",
     "targetUri",
     "headers",
     "timeoutMs",

package/dist/config.js

@@ -328,6 +328,9 @@ export const memoryOpenVikingConfigSchema = {
             value = {};
         }
         const cfg = value;
+        if (cfg.contextManagementMode !== undefined && !["native", "openviking"].includes(String(cfg.contextManagementMode))) {
+            throw new Error("contextManagementMode must be native or openviking");
+        }
         assertAllowedKeys(cfg, [
             "mode",
             "baseUrl",
@@ -340,6 +343,7 @@ export const memoryOpenVikingConfigSchema = {
             "userId",
             "targetUri",
             "timeoutMs",
+            "contextManagementMode",
             "autoCapture",
             "captureMode",
             "captureMaxLength",
@@ -436,6 +440,7 @@ export const memoryOpenVikingConfigSchema = {
             userId,
             targetUri: typeof cfg.targetUri === "string" ? cfg.targetUri : DEFAULT_TARGET_URI,
             timeoutMs: Math.max(1000, Math.floor(toNumber(cfg.timeoutMs, DEFAULT_TIMEOUT_MS))),
+            contextManagementMode: cfg.contextManagementMode === "openviking" ? "openviking" : "native",
             autoCapture: cfg.autoCapture !== false,
             captureMode: captureMode ?? DEFAULT_CAPTURE_MODE,
             captureMaxLength: Math.max(200, Math.min(200_000, Math.floor(toNumber(cfg.captureMaxLength, DEFAULT_CAPTURE_MAX_LENGTH)))),

package/dist/context-engine.js

@@ -191,7 +191,7 @@ export function createMemoryOpenVikingContextEngine(params) {
             id,
             name,
             version,
-            ownsCompaction: true,
+            ownsCompaction: cfg.contextManagementMode === "openviking",
             transcriptSemantics: {
                 currentTurnFence: "before-current-turn-entry-v1",
                 turnAdvancementIdempotency: "atomic-idempotent-v1",
@@ -308,6 +308,7 @@ export function createMemoryOpenVikingContextEngine(params) {
         async compact(compactParams) {
             const tokenBudget = validTokenBudget(compactParams.tokenBudget) ?? 128_000;
             return compactOpenVikingSession({
+                contextManagementMode: cfg.contextManagementMode,
                 sessionId: compactParams.sessionId,
                 sessionKey: resolveSessionKey(compactParams),
                 tokenBudget,

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

@@ -95,13 +95,31 @@ export function registerOpenVikingMemoryTools(deps) {
                     };
                 }
                 if (memoriesCount === 0) {
-                    deps.logger.warn(`openviking: memory_store committed but 0 memories extracted (sessionId=${sessionId}). ` +
-                        "Check OpenViking server logs for embedding/extract errors (e.g. 401 API key, or extraction pipeline).");
-                }
-                else {
-                    deps.logger.info?.(`openviking: memory_store committed, memories=${memoriesCount}, ` +
-                        `trace_id=${commitResult.trace_id ?? "none"}`);
+                    deps.logger.warn(`openviking: memory_store committed but 0 memories extracted (sessionId=${sessionId}), ` +
+                        `trace_id=${commitResult.trace_id ?? "none"}. ` +
+                        "No memory was created or updated. Check memory.extraction_enabled, VLM configuration/API keys, or whether the content is already stored.");
+                    return {
+                        content: [{
+                                type: "text",
+                                text: `Memory extraction completed for session ${sessionId}, but created or updated no memory. ` +
+                                    "The content may already be stored, memory extraction may be disabled, or the extractor found nothing new to store. " +
+                                    "Tell the user no new memory was created." +
+                                    (commitResult.trace_id ? ` (trace_id=${commitResult.trace_id})` : ""),
+                            }],
+                        details: {
+                            action: "failed",
+                            sessionId,
+                            status: commitResult.status,
+                            error: "no_memories_extracted",
+                            memoriesCount,
+                            archived: commitResult.archived ?? false,
+                            traceId: commitResult.trace_id,
+                            usedTempSession,
+                        },
+                    };
                 }
+                deps.logger.info?.(`openviking: memory_store committed, memories=${memoriesCount}, ` +
+                    `trace_id=${commitResult.trace_id ?? "none"}`);
                 return {
                     content: [
                         {

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

@@ -344,12 +344,23 @@ async function assembleSessionContext(params) {
             });
         }
     }
+    if (cfg.contextManagementMode !== "openviking") {
+        return assemblePassthrough({ diag, ovSessionId, reason: "native_context", liveMessages: messages, originalTokens });
+    }
     try {
         const client = await getClient();
         const ctx = await client.getSessionContext(ovSessionId, tokenBudget);
         const preAbstracts = ctx?.pre_archive_abstracts ?? [];
         const hasArchives = !!ctx?.latest_archive_overview || preAbstracts.length > 0;
         const activeCount = ctx?.messages?.length ?? 0;
+        // A completed WM-off archive can leave a non-empty active tail. That tail
+        // alone cannot replace the host's earlier history in explicit OV mode.
+        if (!hasArchives && (ctx?.stats?.totalArchives ?? 0) > 0) {
+            logger.warn?.("openviking: archived context has no summary; keeping native history");
+            return assemblePassthrough({
+                diag, ovSessionId, reason: "archive_summary_missing", liveMessages: messages, originalTokens,
+            });
+        }
         if (!ctx || (!hasArchives && activeCount === 0)) {
             return assemblePassthrough({
                 diag,
@@ -658,6 +669,7 @@ export async function afterTurnOpenVikingSession({ throwOnError = false, session
         }
         const commitResult = await client.commitSession(ovSessionId, {
             wait: false,
+            ...(cfg.contextManagementMode === "openviking" ? { enableWorkingMemory: true } : {}),
             ...(cfg.commitRetentionMode === "turn_budget"
                 ? { retentionMode: "turn_budget" }
                 : { keepRecentCount: cfg.commitKeepRecentCount }),
@@ -666,6 +678,7 @@ export async function afterTurnOpenVikingSession({ throwOnError = false, session
             `status=${commitResult.status}, archived=${commitResult.archived ?? false}, ` +
             `task_id=${commitResult.task_id ?? "none"}, trace_id=${commitResult.trace_id ?? "none"}`);
         diag("afterTurn_commit", ovSessionId, {
+            effectiveEnableWorkingMemory: commitResult.effective_enable_working_memory,
             pendingTokens,
             commitTokenThreshold,
             commitTokenThresholdRatio: cfg.commitTokenThresholdRatio,
@@ -715,7 +728,7 @@ function compactFailureResult(reason, tokensBefore, details) {
         },
     };
 }
-export async function compactOpenVikingSession({ sessionId, sessionKey, tokenBudget, currentTokenCount, force, compactionTarget, customInstructions, getClient, logger, resolveAgentId, isBypassedSession, runtimeCompact, diag, }) {
+export async function compactOpenVikingSession({ contextManagementMode = "native", sessionId, sessionKey, tokenBudget, currentTokenCount, force, compactionTarget, customInstructions, getClient, logger, resolveAgentId, isBypassedSession, runtimeCompact, diag, }) {
     const ovSessionId = openClawSessionToOvStorageId(sessionId, sessionKey);
     diag("compact_entry", ovSessionId, {
         tokenBudget,
@@ -749,6 +762,9 @@ export async function compactOpenVikingSession({ sessionId, sessionKey, tokenBud
             reason: "session_bypassed",
         };
     }
+    if (contextManagementMode === "native") {
+        return await runtimeCompact?.() ?? compactFailureResult("native_compaction_unavailable", validTokenCount(currentTokenCount) ?? -1, { message: "Upgrade OpenClaw to a version with runtime compaction delegation." });
+    }
     const client = await getClient();
     const agentId = resolveAgentId(sessionId, sessionKey, ovSessionId);
     const tokensBeforeOriginal = validTokenCount(currentTokenCount);
@@ -771,6 +787,7 @@ export async function compactOpenVikingSession({ sessionId, sessionKey, tokenBud
         const commitResult = await client.commitSession(ovSessionId, {
             wait: true,
             keepRecentCount: 0,
+            enableWorkingMemory: true,
         });
         const memCount = totalExtractedMemories(commitResult.memories_extracted);
         if (commitResult.status === "failed") {
@@ -828,6 +845,9 @@ export async function compactOpenVikingSession({ sessionId, sessionKey, tokenBud
                 },
             };
         }
+        if (commitResult.effective_enable_working_memory !== true) {
+            return await runtimeCompact?.() ?? compactFailureResult("working_memory_disabled", tokensBefore, { commit: commitResult });
+        }
         let summary = "";
         const firstKeptEntryId = commitResult.archive_uri?.split("/").pop() ?? "";
         let tokensAfter;
@@ -875,6 +895,9 @@ export async function compactOpenVikingSession({ sessionId, sessionKey, tokenBud
         logger.info(`openviking: compact tokens session=${ovSessionId}, ` +
             `tokensBefore=${tokensBefore}, tokensAfter=${tokensAfter ?? "unknown"}, ` +
             `latestArchiveId=${firstKeptEntryId || "none"}`);
+        if (!summary) {
+            return await runtimeCompact?.() ?? compactFailureResult("archive_summary_missing", tokensBefore, { commit: commitResult });
+        }
         diag("compact_result", ovSessionId, {
             ok: true,
             compacted: true,

package/install-manifest.json

@@ -1,6 +1,6 @@
 {
   "manifestVersion": "1.0",
-  "pluginVersion": "2026.9.21",
+  "pluginVersion": "2026.9.22",
   "plugin": {
     "id": "openviking",
     "kind": "context-engine",

package/openclaw.plugin.json

@@ -353,6 +353,12 @@
       "timeoutMs": {
         "type": "number"
       },
+      "contextManagementMode": {
+        "type": "string",
+        "enum": ["native", "openviking"],
+        "default": "native",
+        "description": "Use host history and compaction; openviking explicitly enables Working Memory context management."
+      },
       "autoCapture": {
         "type": "boolean"
       },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openviking/openclaw-plugin",
-  "version": "2026.10.6",
+  "version": "2026.10.7",
   "displayName": "OpenViking",
   "description": "OpenClaw context-engine plugin — OpenViking AI memory, long-term memory, knowledge base, semantic search, RAG, context engine. 长期记忆 · 知识库 · 语义检索 · 上下文引擎",
   "type": "module",

package/plugin/openviking-memory-tools.ts

@@ -176,15 +176,34 @@ export function registerOpenVikingMemoryTools(deps: OpenVikingMemoryToolsDeps):
           }
           if (memoriesCount === 0) {
             deps.logger.warn(
-              `openviking: memory_store committed but 0 memories extracted (sessionId=${sessionId}). ` +
-                "Check OpenViking server logs for embedding/extract errors (e.g. 401 API key, or extraction pipeline).",
-            );
-          } else {
-            deps.logger.info?.(
-              `openviking: memory_store committed, memories=${memoriesCount}, ` +
-                `trace_id=${commitResult.trace_id ?? "none"}`,
+              `openviking: memory_store committed but 0 memories extracted (sessionId=${sessionId}), ` +
+                `trace_id=${commitResult.trace_id ?? "none"}. ` +
+                "No memory was created or updated. Check memory.extraction_enabled, VLM configuration/API keys, or whether the content is already stored.",
             );
+            return {
+              content: [{
+                type: "text",
+                text: `Memory extraction completed for session ${sessionId}, but created or updated no memory. ` +
+                  "The content may already be stored, memory extraction may be disabled, or the extractor found nothing new to store. " +
+                  "Tell the user no new memory was created." +
+                  (commitResult.trace_id ? ` (trace_id=${commitResult.trace_id})` : ""),
+              }],
+              details: {
+                action: "failed",
+                sessionId,
+                status: commitResult.status,
+                error: "no_memories_extracted",
+                memoriesCount,
+                archived: commitResult.archived ?? false,
+                traceId: commitResult.trace_id,
+                usedTempSession,
+              },
+            };
           }
+          deps.logger.info?.(
+            `openviking: memory_store committed, memories=${memoriesCount}, ` +
+              `trace_id=${commitResult.trace_id ?? "none"}`,
+          );
           return {
             content: [
               {

package/services/context-lifecycle-service.ts

@@ -107,6 +107,7 @@ export type AssembleOpenVikingSessionParams = {
 type CompactClient = Pick<OpenVikingClient, "commitSession" | "getSessionContext">;
 
 export type CompactOpenVikingSessionParams = {
+  contextManagementMode?: "native" | "openviking";
   sessionId: string;
   sessionKey?: string;
   tokenBudget: number;
@@ -138,6 +139,7 @@ export type AfterTurnOpenVikingSessionParams = {
   runtimeContext?: Record<string, unknown>;
   cfg: {
     autoCapture: boolean;
+    contextManagementMode?: "native" | "openviking";
     commitTokenThresholdRatio: number;
     commitKeepRecentCount: number;
     commitRetentionMode?: "message_count" | "turn_budget";
@@ -610,6 +612,10 @@ async function assembleSessionContext(params: AssembleOpenVikingSessionParams):
     }
   }
 
+  if (cfg.contextManagementMode !== "openviking") {
+    return assemblePassthrough({ diag, ovSessionId, reason: "native_context", liveMessages: messages, originalTokens });
+  }
+
   try {
     const client = await getClient();
     const ctx = await client.getSessionContext(ovSessionId, tokenBudget);
@@ -618,6 +624,15 @@ async function assembleSessionContext(params: AssembleOpenVikingSessionParams):
     const hasArchives = !!ctx?.latest_archive_overview || preAbstracts.length > 0;
     const activeCount = ctx?.messages?.length ?? 0;
 
+    // A completed WM-off archive can leave a non-empty active tail. That tail
+    // alone cannot replace the host's earlier history in explicit OV mode.
+    if (!hasArchives && (ctx?.stats?.totalArchives ?? 0) > 0) {
+      logger.warn?.("openviking: archived context has no summary; keeping native history");
+      return assemblePassthrough({
+        diag, ovSessionId, reason: "archive_summary_missing", liveMessages: messages, originalTokens,
+      });
+    }
+
     if (!ctx || (!hasArchives && activeCount === 0)) {
       return assemblePassthrough({
         diag,
@@ -989,6 +1004,7 @@ export async function afterTurnOpenVikingSession({
 
     const commitResult = await client.commitSession(ovSessionId, {
       wait: false,
+      ...(cfg.contextManagementMode === "openviking" ? { enableWorkingMemory: true } : {}),
       ...(cfg.commitRetentionMode === "turn_budget"
         ? { retentionMode: "turn_budget" as const }
         : { keepRecentCount: cfg.commitKeepRecentCount }),
@@ -1000,6 +1016,7 @@ export async function afterTurnOpenVikingSession({
     );
 
     diag("afterTurn_commit", ovSessionId, {
+      effectiveEnableWorkingMemory: commitResult.effective_enable_working_memory,
       pendingTokens,
       commitTokenThreshold,
       commitTokenThresholdRatio: cfg.commitTokenThresholdRatio,
@@ -1058,6 +1075,7 @@ function compactFailureResult(
 }
 
 export async function compactOpenVikingSession({
+  contextManagementMode = "native",
   sessionId,
   sessionKey,
   tokenBudget,
@@ -1107,6 +1125,13 @@ export async function compactOpenVikingSession({
     };
   }
 
+  if (contextManagementMode === "native") {
+    return await runtimeCompact?.() ?? compactFailureResult(
+      "native_compaction_unavailable", validTokenCount(currentTokenCount) ?? -1,
+      { message: "Upgrade OpenClaw to a version with runtime compaction delegation." },
+    );
+  }
+
   const client = await getClient();
   const agentId = resolveAgentId(sessionId, sessionKey, ovSessionId);
   const tokensBeforeOriginal = validTokenCount(currentTokenCount);
@@ -1134,6 +1159,7 @@ export async function compactOpenVikingSession({
     const commitResult = await client.commitSession(ovSessionId, {
       wait: true,
       keepRecentCount: 0,
+      enableWorkingMemory: true,
     });
     const memCount = totalExtractedMemories(commitResult.memories_extracted);
 
@@ -1204,6 +1230,10 @@ export async function compactOpenVikingSession({
       };
     }
 
+    if (commitResult.effective_enable_working_memory !== true) {
+      return await runtimeCompact?.() ?? compactFailureResult("working_memory_disabled", tokensBefore, { commit: commitResult });
+    }
+
     let summary = "";
     const firstKeptEntryId = commitResult.archive_uri?.split("/").pop() ?? "";
     let tokensAfter: number | undefined;
@@ -1264,6 +1294,10 @@ export async function compactOpenVikingSession({
         `latestArchiveId=${firstKeptEntryId || "none"}`,
     );
 
+    if (!summary) {
+      return await runtimeCompact?.() ?? compactFailureResult("archive_summary_missing", tokensBefore, { commit: commitResult });
+    }
+
     diag("compact_result", ovSessionId, {
       ok: true,
       compacted: true,

package/skills/ov-experience-memory/SKILL.md

@@ -30,7 +30,7 @@ Choose the registered names that match the current runtime:
 | Runtime | Search | Read |
 | --- | --- | --- |
 | OpenViking MCP, Codex, Claude Code | `find` or `search` | `read` |
-| OpenCode | `openviking_find` or `openviking_search` | `openviking_read` |
+| OpenCode, pi | `openviking_find` or `openviking_search` | `openviking_read` |
 | OpenClaw | `ov_search` | `ov_read` or `ov_multi_read` |
 
 The host may display MCP names with a namespace such as