@openviking/openclaw-plugin 2026.9.11 → 2026.9.13

package/README.md

@@ -227,6 +227,14 @@ After that, the plugin checks `pending_tokens`. Once it reaches `commitTokenThre
 
 Memory extraction on this automatic path is commit-dependent. Short but important facts can stay only in the live session until a threshold commit, `/compact`, or an explicit store happens.
 
+Auto-commit keeps the most recent 10 messages by default (`commitKeepRecentCount`). This count-based window can start mid-turn. With a server that supports turn-aware retention, set `"commitRetentionMode": "turn_budget"` in the plugin config to opt in:
+
+- `commitKeepRecentCount` is ignored. The server defaults apply: up to 3 recent user turns, a 12,000-token retention budget, and at least the final assistant/tool step.
+- For an oversized newest turn, the server retains its user question and recent steps and checkpoints the archived prefix. The mandatory tail can exceed the retention budget.
+- `pending_tokens` counts only messages that will leave the live window, not a user question shared with the archive.
+
+Manual commit and `/compact` still archive everything. Leave the option unset (or use `"message_count"`) to preserve existing behavior.
+
 ### Explicit long-term memory writes
 
 When the user explicitly asks the agent to remember, save, or store an important long-term fact, preference, project, or decision, prefer `memory_store` over waiting for normal auto-capture. `memory_store` writes the text to an OpenViking session and calls `commit(wait=true)`, so it is the reliable integration-side path for facts that should be available as long-term memory as soon as possible.

package/client.ts

@@ -848,6 +848,8 @@ export class OpenVikingClient {
       keepRecentCount?: number;
       /** Start empty context in the same session after archiving. */
       resetContext?: boolean;
+      /** Opt in to the server's turn-aware defaults instead of message-count retention. */
+      retentionMode?: "turn_budget";
       agentId?: string;
     },
   ): Promise<CommitSessionResult> {
@@ -862,11 +864,14 @@ export class OpenVikingClient {
         sessionId,
         wait: options?.wait ?? false,
         keepRecentCount,
+        retentionMode: options?.retentionMode,
       },
       options?.agentId,
     );
     const body: Record<string, unknown> = {};
-    if (keepRecentCount > 0) {
+    if (options?.retentionMode === "turn_budget") {
+      body.retention_mode = "turn_budget";
+    } else if (keepRecentCount > 0) {
       body.keep_recent_count = keepRecentCount;
     }
     if (options?.resetContext) {

package/commands/setup.ts

@@ -82,6 +82,7 @@ const CONFIG_KEYS_TO_PRESERVE = [
   "recallPreferAbstract",
   "recallTokenBudget",
   "commitTokenThresholdRatio",
+  "commitRetentionMode",
   "commitKeepRecentCount",
   "bypassSessionPatterns",
   "emitStandardDiagnostics",

package/config.ts

@@ -68,11 +68,13 @@ export type MemoryOpenVikingConfig = {
    * compatibility). Set to 0 to commit every turn.
    */
   commitTokenThresholdRatio?: number;
+  /** Auto-commit retention: legacy message count (default) or the server's turn-budget policy. */
+  commitRetentionMode?: "message_count" | "turn_budget";
   /**
    * WM v2: number of most-recent messages to keep live after an afterTurn
    * commit so the next turn still has immediate context. Forwarded to the
-   * server as `keep_recent_count`. Default 10. The compact path ignores this
-   * value and always passes 0.
+   * server as `keep_recent_count`. Default 10. Ignored in turn_budget mode.
+   * The compact path ignores this value and always passes 0.
    */
   commitKeepRecentCount?: number;
   bypassSessionPatterns?: string[];
@@ -538,6 +540,7 @@ export const memoryOpenVikingConfigSchema = {
         "recallTokenBudget",
         "commitTokenThreshold",
         "commitTokenThresholdRatio",
+        "commitRetentionMode",
         "commitKeepRecentCount",
         "bypassSessionPatterns",
         "ingestReplyAssist",
@@ -588,6 +591,14 @@ export const memoryOpenVikingConfigSchema = {
         ? (cfg.apiKey as string | OpenVikingSecretRef)
         : getEnv("OPENVIKING_API_KEY") || undefined;
     const captureMode = cfg.captureMode;
+    const commitRetentionMode = cfg.commitRetentionMode;
+    if (
+      commitRetentionMode !== undefined &&
+      commitRetentionMode !== "message_count" &&
+      commitRetentionMode !== "turn_budget"
+    ) {
+      throw new Error('openviking commitRetentionMode must be "message_count" or "turn_budget"');
+    }
     if (
       typeof captureMode !== "undefined" &&
       captureMode !== "semantic" &&
@@ -666,6 +677,7 @@ export const memoryOpenVikingConfigSchema = {
         0,
         Math.min(1, toNumber(cfg.commitTokenThresholdRatio, DEFAULT_COMMIT_TOKEN_THRESHOLD_RATIO)),
       ),
+      commitRetentionMode: commitRetentionMode ?? "message_count",
       commitKeepRecentCount: Math.max(
         0,
         Math.min(
@@ -916,13 +928,18 @@ export const memoryOpenVikingConfigSchema = {
       advanced: true,
       help: "Auto-commit triggers once estimated pending tokens reach this fraction (0-1) of the model context window (e.g. 0.5 = 50%). Set to 0 to commit every turn.",
     },
+    commitRetentionMode: {
+      label: "Commit Retention Mode",
+      advanced: true,
+      help: "Auto-commit only: message_count (default) keeps recent messages; turn_budget uses the server's turn-aware defaults. Manual commit and compact still archive everything.",
+    },
     commitKeepRecentCount: {
       label: "Commit Keep Recent Count",
       placeholder: String(DEFAULT_COMMIT_KEEP_RECENT_COUNT),
       advanced: true,
       help:
         "Number of most-recent messages to keep live after an afterTurn commit. " +
-        "Forwarded as keep_recent_count to the server. Compact path always uses 0.",
+        "Forwarded as keep_recent_count to the server in message_count mode; ignored in turn_budget mode. Compact path always uses 0.",
     },
     emitStandardDiagnostics: {
       label: "Standard diagnostics (diag JSON lines)",

package/dist/client.js

@@ -410,9 +410,13 @@ export class OpenVikingClient {
             sessionId,
             wait: options?.wait ?? false,
             keepRecentCount,
+            retentionMode: options?.retentionMode,
         }, options?.agentId);
         const body = {};
-        if (keepRecentCount > 0) {
+        if (options?.retentionMode === "turn_budget") {
+            body.retention_mode = "turn_budget";
+        }
+        else if (keepRecentCount > 0) {
             body.keep_recent_count = keepRecentCount;
         }
         if (options?.resetContext) {

package/dist/commands/setup.js

@@ -72,6 +72,7 @@ const CONFIG_KEYS_TO_PRESERVE = [
     "recallPreferAbstract",
     "recallTokenBudget",
     "commitTokenThresholdRatio",
+    "commitRetentionMode",
     "commitKeepRecentCount",
     "bypassSessionPatterns",
     "emitStandardDiagnostics",

package/dist/config.js

@@ -354,6 +354,7 @@ export const memoryOpenVikingConfigSchema = {
             "recallTokenBudget",
             "commitTokenThreshold",
             "commitTokenThresholdRatio",
+            "commitRetentionMode",
             "commitKeepRecentCount",
             "bypassSessionPatterns",
             "ingestReplyAssist",
@@ -396,6 +397,12 @@ export const memoryOpenVikingConfigSchema = {
             ? cfg.apiKey
             : getEnv("OPENVIKING_API_KEY") || undefined;
         const captureMode = cfg.captureMode;
+        const commitRetentionMode = cfg.commitRetentionMode;
+        if (commitRetentionMode !== undefined &&
+            commitRetentionMode !== "message_count" &&
+            commitRetentionMode !== "turn_budget") {
+            throw new Error('openviking commitRetentionMode must be "message_count" or "turn_budget"');
+        }
         if (typeof captureMode !== "undefined" &&
             captureMode !== "semantic" &&
             captureMode !== "keyword") {
@@ -437,6 +444,7 @@ export const memoryOpenVikingConfigSchema = {
             recallMaxInjectedChars,
             recallTokenBudget: recallMaxInjectedChars,
             commitTokenThresholdRatio: Math.max(0, Math.min(1, toNumber(cfg.commitTokenThresholdRatio, DEFAULT_COMMIT_TOKEN_THRESHOLD_RATIO))),
+            commitRetentionMode: commitRetentionMode ?? "message_count",
             commitKeepRecentCount: Math.max(0, Math.min(1_000, Math.floor(toNumber(cfg.commitKeepRecentCount, DEFAULT_COMMIT_KEEP_RECENT_COUNT)))),
             bypassSessionPatterns: toStringArray(cfg.bypassSessionPatterns, toStringArray(cfg.ingestReplyAssistIgnoreSessionPatterns, DEFAULT_BYPASS_SESSION_PATTERNS)),
             emitStandardDiagnostics: typeof cfg.emitStandardDiagnostics === "boolean"
@@ -612,12 +620,17 @@ export const memoryOpenVikingConfigSchema = {
             advanced: true,
             help: "Auto-commit triggers once estimated pending tokens reach this fraction (0-1) of the model context window (e.g. 0.5 = 50%). Set to 0 to commit every turn.",
         },
+        commitRetentionMode: {
+            label: "Commit Retention Mode",
+            advanced: true,
+            help: "Auto-commit only: message_count (default) keeps recent messages; turn_budget uses the server's turn-aware defaults. Manual commit and compact still archive everything.",
+        },
         commitKeepRecentCount: {
             label: "Commit Keep Recent Count",
             placeholder: String(DEFAULT_COMMIT_KEEP_RECENT_COUNT),
             advanced: true,
             help: "Number of most-recent messages to keep live after an afterTurn commit. " +
-                "Forwarded as keep_recent_count to the server. Compact path always uses 0.",
+                "Forwarded as keep_recent_count to the server in message_count mode; ignored in turn_budget mode. Compact path always uses 0.",
         },
         emitStandardDiagnostics: {
             label: "Standard diagnostics (diag JSON lines)",

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

@@ -657,7 +657,9 @@ export async function afterTurnOpenVikingSession({ throwOnError = false, session
         }
         const commitResult = await client.commitSession(ovSessionId, {
             wait: false,
-            keepRecentCount: cfg.commitKeepRecentCount,
+            ...(cfg.commitRetentionMode === "turn_budget"
+                ? { retentionMode: "turn_budget" }
+                : { keepRecentCount: cfg.commitKeepRecentCount }),
         });
         logger.info(`openviking: committed session=${ovSessionId}, ` +
             `status=${commitResult.status}, archived=${commitResult.archived ?? false}, ` +

package/openclaw.plugin.json

@@ -204,11 +204,16 @@
       "advanced": true,
       "help": "Auto-commit triggers once estimated pending tokens reach this fraction (0-1) of the model context window (e.g. 0.5 = 50%). Set to 0 to commit every turn."
     },
+    "commitRetentionMode": {
+      "label": "Commit Retention Mode",
+      "advanced": true,
+      "help": "Auto-commit only: message_count (default) keeps recent messages; turn_budget uses the server's turn-aware defaults. Manual commit and compact still archive everything."
+    },
     "commitKeepRecentCount": {
       "label": "Commit Keep Recent Count",
       "placeholder": "10",
       "advanced": true,
-      "help": "WM v2: number of most-recent messages kept live after an afterTurn commit. Compact path always uses 0."
+      "help": "Number of most-recent messages kept live after an afterTurn commit in message_count mode; ignored in turn_budget mode. Compact path always uses 0."
     },
     "emitStandardDiagnostics": {
       "label": "Standard diagnostics (diag JSON lines)",
@@ -405,6 +410,10 @@
         "minimum": 0,
         "maximum": 1
       },
+      "commitRetentionMode": {
+        "type": "string",
+        "enum": ["message_count", "turn_budget"]
+      },
       "commitKeepRecentCount": {
         "type": "number",
         "minimum": 0,

package/package.json

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

package/services/context-lifecycle-service.ts

@@ -140,6 +140,7 @@ export type AfterTurnOpenVikingSessionParams = {
     autoCapture: boolean;
     commitTokenThresholdRatio: number;
     commitKeepRecentCount: number;
+    commitRetentionMode?: "message_count" | "turn_budget";
     logFindRequests: boolean;
     peer_role?: OpenVikingPeerRole;
   };
@@ -987,7 +988,9 @@ export async function afterTurnOpenVikingSession({
 
     const commitResult = await client.commitSession(ovSessionId, {
       wait: false,
-      keepRecentCount: cfg.commitKeepRecentCount,
+      ...(cfg.commitRetentionMode === "turn_budget"
+        ? { retentionMode: "turn_budget" as const }
+        : { keepRecentCount: cfg.commitKeepRecentCount }),
     });
     logger.info(
       `openviking: committed session=${ovSessionId}, ` +