@openviking/openclaw-plugin 2026.9.10 → 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/auto-recall.ts

@@ -331,6 +331,7 @@ export async function buildAutoRecallContext(params: {
   rawUserTextPreview?: string;
   queryTruncated?: boolean;
   resourceTypes?: RecallResourceType[];
+  dedupTurns?: number;
 }): Promise<{ block?: string; memoryCount: number; estimatedTokens: number }> {
   const { cfg, client, agentId, actorPeerId, queryText, logger, verbose } = params;
   const queryConfig = params.queryConfig;
@@ -373,7 +374,7 @@ export async function buildAutoRecallContext(params: {
           queryExpansion: "auto",
           maxTokens,
           detail: recallPreferAbstract ? "abstract" : undefined,
-          dedupTurns: params.ovSessionId ? AUTO_RECALL_DEDUP_TURNS : undefined,
+          dedupTurns: params.dedupTurns ?? (params.ovSessionId ? AUTO_RECALL_DEDUP_TURNS : undefined),
           peerScope: "actor",
           actorPeerId,
           requestTimeoutMs: cfg.autoRecallTimeoutMs,

package/client.ts

@@ -80,6 +80,7 @@ export type CommitSessionResult = {
   task_id?: string;
   archive_uri?: string;
   archived?: boolean;
+  reset_context?: boolean;
   /** Present when wait=true and extraction completed. Keyed by category. */
   memories_extracted?: Record<string, number>;
   error?: string;
@@ -508,6 +509,7 @@ export class OpenVikingClient {
     };
     const body = {
       ...buildContextSearchBody(contractConfig, { sessionId: options.sessionId }),
+      ...(options.dedupTurns === 0 ? { dedup_turns: 0 } : {}),
       query,
       ...(options.contextType !== undefined ? { context_type: options.contextType } : {}),
       ...(options.detail !== undefined ? { detail: options.detail } : {}),
@@ -844,6 +846,10 @@ export class OpenVikingClient {
        * preserves the pre-v2 "archive everything" behavior.
       */
       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> {
@@ -858,13 +864,19 @@ 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) {
+      body.reset_context = true;
+    }
     const result = await this.request<CommitSessionResult>(
       `/api/v1/sessions/${encodeURIComponent(sessionId)}/commit`,
       { method: "POST", body: JSON.stringify(body) },
@@ -872,6 +884,10 @@ export class OpenVikingClient {
       options?.agentId,
     );
 
+    if (options?.resetContext && result.reset_context !== true) {
+      throw new Error("OpenViking server did not confirm reset_context; upgrade the server with the plugin.");
+    }
+
     if (!options?.wait || !result.task_id) {
       return result;
     }

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/context-engine.ts

@@ -394,6 +394,7 @@ export function createMemoryOpenVikingContextEngine(params: {
         sessionId: assembleParams.sessionId,
         sessionKey: resolveSessionKey(assembleParams),
         messages: assembleParams.messages,
+        prompt: assembleParams.prompt,
         tokenBudget,
         runtimeContext: assembleParams.runtimeContext,
         isMainAssemble,

package/dist/auto-recall.js

@@ -244,7 +244,7 @@ export async function buildAutoRecallContext(params) {
                 queryExpansion: "auto",
                 maxTokens,
                 detail: recallPreferAbstract ? "abstract" : undefined,
-                dedupTurns: params.ovSessionId ? AUTO_RECALL_DEDUP_TURNS : undefined,
+                dedupTurns: params.dedupTurns ?? (params.ovSessionId ? AUTO_RECALL_DEDUP_TURNS : undefined),
                 peerScope: "actor",
                 actorPeerId,
                 requestTimeoutMs: cfg.autoRecallTimeoutMs,

package/dist/client.js

@@ -205,6 +205,7 @@ export class OpenVikingClient {
         };
         const body = {
             ...buildContextSearchBody(contractConfig, { sessionId: options.sessionId }),
+            ...(options.dedupTurns === 0 ? { dedup_turns: 0 } : {}),
             query,
             ...(options.contextType !== undefined ? { context_type: options.contextType } : {}),
             ...(options.detail !== undefined ? { detail: options.detail } : {}),
@@ -409,12 +410,22 @@ 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) {
+            body.reset_context = true;
+        }
         const result = await this.request(`/api/v1/sessions/${encodeURIComponent(sessionId)}/commit`, { method: "POST", body: JSON.stringify(body) }, undefined, options?.agentId);
+        if (options?.resetContext && result.reset_context !== true) {
+            throw new Error("OpenViking server did not confirm reset_context; upgrade the server with the plugin.");
+        }
         if (!options?.wait || !result.task_id) {
             return result;
         }

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/context-engine.js

@@ -214,6 +214,7 @@ export function createMemoryOpenVikingContextEngine(params) {
                 sessionId: assembleParams.sessionId,
                 sessionKey: resolveSessionKey(assembleParams),
                 messages: assembleParams.messages,
+                prompt: assembleParams.prompt,
                 tokenBudget,
                 runtimeContext: assembleParams.runtimeContext,
                 isMainAssemble,

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

@@ -157,6 +157,7 @@ export async function commitOpenVikingSession({ sessionId, sessionKey, getClient
         const commitResult = await client.commitSession(ovId, {
             wait: true,
             keepRecentCount: 0,
+            resetContext: true,
         });
         const memCount = totalExtractedMemories(commitResult.memories_extracted);
         if (commitResult.status === "failed") {
@@ -195,7 +196,73 @@ function isSessionNotFoundError(err) {
     const errorMessage = String(err);
     return errorMessage.includes("[NOT_FOUND]") && errorMessage.includes("Session not found");
 }
-export async function assembleOpenVikingSession({ sessionId, sessionKey, messages, tokenBudget, runtimeContext, isMainAssemble, cfg, getClient, logger, resolveAgentId, rememberSessionAgentId, isBypassedSession, queryConfigStore, traceRecorder, diag, roughEstimate, messageDigest, extractAgentMessageText, hasAutoRecallBlock, prependRecallToLatestUserMessage, }) {
+async function recallForAssemble(params, recallQuery) {
+    const { sessionId, sessionKey, cfg, getClient, resolveAgentId, queryConfigStore, logger, traceRecorder } = params;
+    const ovSessionId = openClawSessionToOvStorageId(sessionId, sessionKey);
+    const sender = extractRuntimeSenderId(params.runtimeContext);
+    const client = await getClient();
+    const routingRef = sessionId ?? sessionKey ?? ovSessionId;
+    const agentId = resolveAgentId(routingRef, sessionKey, ovSessionId);
+    const actorPeerId = resolveOpenVikingActorPeerId({
+        peerRole: cfg.peer_role ?? "none",
+        senderPeerId: sanitizeOpenVikingPeerId(sender.senderId),
+        assistantPeerId: agentId,
+    });
+    const queryConfig = await queryConfigStore?.getEffective({
+        agentId,
+        sessionId,
+        sessionKey,
+        ovSessionId,
+    });
+    return buildAutoRecallContext({
+        cfg,
+        queryConfig,
+        client,
+        agentId,
+        actorPeerId,
+        queryText: recallQuery.query,
+        logger,
+        verbose: (message) => logger.info(message),
+        traceRecorder: traceRecorder,
+        sessionId,
+        sessionKey,
+        ovSessionId,
+        queryTruncated: recallQuery.truncated,
+        rawUserTextPreview: recallQuery.query,
+        // System additions are transient; the next turn must be able to recall the same URI.
+        dedupTurns: params.isMainAssemble ? 0 : undefined,
+    });
+}
+export async function assembleOpenVikingSession(params) {
+    const assembled = await assembleSessionContext(params);
+    // Current OpenClaw supplies the pending turn separately from history. Keep
+    // recalled context out of persisted messages and let the host own that turn.
+    if (!params.isMainAssemble || !params.cfg.autoRecall || !params.prompt ||
+        params.isBypassedSession(params)) {
+        return assembled;
+    }
+    const query = prepareRecallQuery(params.prompt);
+    if (query.query.length < 5)
+        return assembled;
+    try {
+        const recall = await recallForAssemble(params, query);
+        if (!recall.block)
+            return assembled;
+        const systemPromptAddition = [assembled.systemPromptAddition, recall.block].filter(Boolean).join("\n\n");
+        const estimatedTokens = assembled.estimatedTokens
+            + estimateTextTokens(systemPromptAddition)
+            - estimateTextTokens(assembled.systemPromptAddition ?? "");
+        if (estimatedTokens > params.tokenBudget)
+            return assembled;
+        return { ...assembled, systemPromptAddition, estimatedTokens };
+    }
+    catch (err) {
+        params.logger.warn?.(`openviking: auto-recall failed: ${String(err)}`);
+        return assembled;
+    }
+}
+async function assembleSessionContext(params) {
+    const { sessionId, sessionKey, messages, tokenBudget, runtimeContext, isMainAssemble, cfg, getClient, logger, resolveAgentId, rememberSessionAgentId, isBypassedSession, diag, roughEstimate, messageDigest, extractAgentMessageText, hasAutoRecallBlock, prependRecallToLatestUserMessage, } = params;
     const latestMessage = messages.at(-1);
     const isTransformContextAssemble = !isMainAssemble;
     // Tool-loop calls do no recall work on non-user tails; avoid scanning the full history.
@@ -239,36 +306,7 @@ export async function assembleOpenVikingSession({ sessionId, sessionKey, message
                 `chars=${recallQuery.originalChars}->${recallQuery.finalChars})`);
         }
         try {
-            const client = await getClient();
-            const routingRef = sessionId ?? sessionKey ?? ovSessionId;
-            const agentId = resolveAgentId(routingRef, sessionKey, ovSessionId);
-            const actorPeerId = resolveOpenVikingActorPeerId({
-                peerRole: cfg.peer_role ?? "none",
-                senderPeerId: sanitizeOpenVikingPeerId(sender.senderId),
-                assistantPeerId: agentId,
-            });
-            const queryConfig = await queryConfigStore?.getEffective({
-                agentId,
-                sessionId,
-                sessionKey,
-                ovSessionId,
-            });
-            const recall = await buildAutoRecallContext({
-                cfg,
-                queryConfig,
-                client,
-                agentId,
-                actorPeerId,
-                queryText: recallQuery.query,
-                logger,
-                verbose: (message) => logger.info(message),
-                traceRecorder: traceRecorder,
-                sessionId,
-                sessionKey,
-                ovSessionId,
-                queryTruncated: recallQuery.truncated,
-                rawUserTextPreview: recallQuery.query,
-            });
+            const recall = await recallForAssemble(params, recallQuery);
             if (!recall.block) {
                 return assemblePassthrough({
                     diag,
@@ -619,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.10",
+  "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

@@ -72,6 +72,7 @@ export type AssembleOpenVikingSessionParams = {
   sessionId: string;
   sessionKey?: string;
   messages: AgentMessage[];
+  prompt?: string;
   tokenBudget: number;
   runtimeContext?: Record<string, unknown>;
   isMainAssemble: boolean;
@@ -139,6 +140,7 @@ export type AfterTurnOpenVikingSessionParams = {
     autoCapture: boolean;
     commitTokenThresholdRatio: number;
     commitKeepRecentCount: number;
+    commitRetentionMode?: "message_count" | "turn_budget";
     logFindRequests: boolean;
     peer_role?: OpenVikingPeerRole;
   };
@@ -369,6 +371,7 @@ export async function commitOpenVikingSession({
     const commitResult = await client.commitSession(ovId, {
       wait: true,
       keepRecentCount: 0,
+      resetContext: true,
     });
     const memCount = totalExtractedMemories(commitResult.memories_extracted);
     if (commitResult.status === "failed") {
@@ -423,28 +426,98 @@ function isSessionNotFoundError(err: unknown): boolean {
   return errorMessage.includes("[NOT_FOUND]") && errorMessage.includes("Session not found");
 }
 
-export async function assembleOpenVikingSession({
-  sessionId,
-  sessionKey,
-  messages,
-  tokenBudget,
-  runtimeContext,
-  isMainAssemble,
-  cfg,
-  getClient,
-  logger,
-  resolveAgentId,
-  rememberSessionAgentId,
-  isBypassedSession,
-  queryConfigStore,
-  traceRecorder,
-  diag,
-  roughEstimate,
-  messageDigest,
-  extractAgentMessageText,
-  hasAutoRecallBlock,
-  prependRecallToLatestUserMessage,
-}: AssembleOpenVikingSessionParams): Promise<AssembleOpenVikingSessionResult> {
+async function recallForAssemble(
+  params: AssembleOpenVikingSessionParams,
+  recallQuery: ReturnType<typeof prepareRecallQuery>,
+) {
+  const { sessionId, sessionKey, cfg, getClient, resolveAgentId, queryConfigStore, logger, traceRecorder } = params;
+  const ovSessionId = openClawSessionToOvStorageId(sessionId, sessionKey);
+  const sender = extractRuntimeSenderId(params.runtimeContext);
+  const client = await getClient();
+  const routingRef = sessionId ?? sessionKey ?? ovSessionId;
+  const agentId = resolveAgentId(routingRef, sessionKey, ovSessionId);
+  const actorPeerId = resolveOpenVikingActorPeerId({
+    peerRole: cfg.peer_role ?? "none",
+    senderPeerId: sanitizeOpenVikingPeerId(sender.senderId),
+    assistantPeerId: agentId,
+  });
+  const queryConfig = await queryConfigStore?.getEffective({
+    agentId,
+    sessionId,
+    sessionKey,
+    ovSessionId,
+  });
+  return buildAutoRecallContext({
+    cfg,
+    queryConfig,
+    client,
+    agentId,
+    actorPeerId,
+    queryText: recallQuery.query,
+    logger,
+    verbose: (message) => logger.info(message),
+    traceRecorder: traceRecorder as never,
+    sessionId,
+    sessionKey,
+    ovSessionId,
+    queryTruncated: recallQuery.truncated,
+    rawUserTextPreview: recallQuery.query,
+    // System additions are transient; the next turn must be able to recall the same URI.
+    dedupTurns: params.isMainAssemble ? 0 : undefined,
+  });
+}
+
+export async function assembleOpenVikingSession(
+  params: AssembleOpenVikingSessionParams,
+): Promise<AssembleOpenVikingSessionResult> {
+  const assembled = await assembleSessionContext(params);
+  // Current OpenClaw supplies the pending turn separately from history. Keep
+  // recalled context out of persisted messages and let the host own that turn.
+  if (
+    !params.isMainAssemble || !params.cfg.autoRecall || !params.prompt ||
+    params.isBypassedSession(params)
+  ) {
+    return assembled;
+  }
+  const query = prepareRecallQuery(params.prompt);
+  if (query.query.length < 5) return assembled;
+
+  try {
+    const recall = await recallForAssemble(params, query);
+    if (!recall.block) return assembled;
+    const systemPromptAddition = [assembled.systemPromptAddition, recall.block].filter(Boolean).join("\n\n");
+    const estimatedTokens = assembled.estimatedTokens
+      + estimateTextTokens(systemPromptAddition)
+      - estimateTextTokens(assembled.systemPromptAddition ?? "");
+    if (estimatedTokens > params.tokenBudget) return assembled;
+    return { ...assembled, systemPromptAddition, estimatedTokens };
+  } catch (err) {
+    params.logger.warn?.(`openviking: auto-recall failed: ${String(err)}`);
+    return assembled;
+  }
+}
+
+async function assembleSessionContext(params: AssembleOpenVikingSessionParams): Promise<AssembleOpenVikingSessionResult> {
+  const {
+    sessionId,
+    sessionKey,
+    messages,
+    tokenBudget,
+    runtimeContext,
+    isMainAssemble,
+    cfg,
+    getClient,
+    logger,
+    resolveAgentId,
+    rememberSessionAgentId,
+    isBypassedSession,
+    diag,
+    roughEstimate,
+    messageDigest,
+    extractAgentMessageText,
+    hasAutoRecallBlock,
+    prependRecallToLatestUserMessage,
+  } = params;
   const latestMessage = messages.at(-1);
   const isTransformContextAssemble = !isMainAssemble;
 
@@ -497,36 +570,7 @@ export async function assembleOpenVikingSession({
     }
 
     try {
-      const client = await getClient();
-      const routingRef = sessionId ?? sessionKey ?? ovSessionId;
-      const agentId = resolveAgentId(routingRef, sessionKey, ovSessionId);
-      const actorPeerId = resolveOpenVikingActorPeerId({
-        peerRole: cfg.peer_role ?? "none",
-        senderPeerId: sanitizeOpenVikingPeerId(sender.senderId),
-        assistantPeerId: agentId,
-      });
-      const queryConfig = await queryConfigStore?.getEffective({
-        agentId,
-        sessionId,
-        sessionKey,
-        ovSessionId,
-      });
-      const recall = await buildAutoRecallContext({
-        cfg,
-        queryConfig,
-        client,
-        agentId,
-        actorPeerId,
-        queryText: recallQuery.query,
-        logger,
-        verbose: (message) => logger.info(message),
-        traceRecorder: traceRecorder as never,
-        sessionId,
-        sessionKey,
-        ovSessionId,
-        queryTruncated: recallQuery.truncated,
-        rawUserTextPreview: recallQuery.query,
-      });
+      const recall = await recallForAssemble(params, recallQuery);
 
       if (!recall.block) {
         return assemblePassthrough({
@@ -944,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}, ` +