@openviking/openclaw-plugin 2026.9.11 → 2026.9.15

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/dist/shared/recall-core.mjs

@@ -27,6 +27,28 @@ const CODING_QUOTA_WEIGHTS = {
     skills: 2,
 };
 let userSpaceCache = "";
+/**
+ * Is recall on for this config?
+ *
+ * The switch has four spellings in the wild: a boolean `autoRecall`, opencode's
+ * `{ enabled }` object, dsh and pi's `syncTurns`, and the global `enabled`
+ * that turns the whole plugin off. Reading it here rather than in each loader
+ * is what keeps it from drifting a fifth time — and any spelling that says off
+ * wins, so a config that disables recall under an older name still disables it.
+ */
+export function isRecallEnabled(cfg = {}) {
+    return isSwitchOn([cfg.enabled, cfg.autoRecall, cfg.recall, cfg.syncRecall]);
+}
+/** Any recognised spelling that says off wins; everything else means on. */
+function isSwitchOn(values) {
+    for (const value of values) {
+        if (value === false)
+            return false;
+        if (value && typeof value === "object" && !Array.isArray(value) && value.enabled === false)
+            return false;
+    }
+    return true;
+}
 export function estimateTokens(text) {
     return text ? Math.ceil(String(text).length / 4) : 0;
 }
@@ -323,9 +345,8 @@ async function resolveItemContent(fetchJSON, item, cfg, actorPeerId = "") {
     return content;
 }
 async function buildFallbackInjectionBlock(fetchJSON, items, cfg, actorPeerId = "", log = () => { }) {
-    if (items.length === 0)
-        return null;
-    let budgetRemaining = Math.max(200, Number(cfg.recallTokenBudget || 2000));
+    const budgetTotal = Math.max(200, Number(cfg.recallTokenBudget || 2000));
+    let budgetRemaining = budgetTotal;
     const lines = [
         "<openviking-context>",
         "Relevant context from OpenViking. Use the read MCP tool to expand URIs.",
@@ -355,14 +376,14 @@ async function buildFallbackInjectionBlock(fetchJSON, items, cfg, actorPeerId =
         }
     }
     lines.push("</openviking-context>");
-    const budgetUsed = Math.max(200, Number(cfg.recallTokenBudget || 2000)) - budgetRemaining;
+    const budgetUsed = budgetTotal - budgetRemaining;
     log("recall_injection_built", {
         contentItems: contentCount,
         hintItems: hintCount,
         budgetUsed,
-        budgetTotal: Math.max(200, Number(cfg.recallTokenBudget || 2000)),
+        budgetTotal,
     });
-    return lines.join("\n");
+    return { block: lines.join("\n"), contentCount, hintCount, budgetUsed, stage: "ranked" };
 }
 const LEGACY_CACHE_TTL_MS = 6 * 60 * 60 * 1000;
 function stateFile(name) {
@@ -594,8 +615,13 @@ export async function postRecall(fetchJSON, body, opts = {}) {
  * `"actor"` that sweep is off by definition, so the old peer is asked for
  * separately — as itself, which is both cheaper and wider than a bare
  * cross-peer read (that would need the user id, and reaches memories only).
+ *
+ * `stage` names the path the block came from, which is what a host needs to
+ * tell "the server had nothing" (`no_results`) from "the score threshold
+ * dropped everything" (`filtered_out`) when the block is empty, and a
+ * `server_assembled` block from a `ranked` one when it is not.
  */
-export async function buildRecallBlock(fetchJSON, cfg, query, options = {}) {
+export async function buildRecallBlockDetailed(fetchJSON, cfg, query, options = {}) {
     const primary = await recallForPeer(fetchJSON, cfg, query, options);
     const legacyPeerId = String(options.legacyPeerId || "").trim();
     const actorPeerId = options.actorPeerId ?? cfg.peerId ?? "";
@@ -603,17 +629,31 @@ export async function buildRecallBlock(fetchJSON, cfg, query, options = {}) {
         return primary;
     const log = options.log || (() => { });
     const legacy = await recallForPeer(fetchJSON, cfg, query, { ...options, actorPeerId: legacyPeerId });
-    if (!legacy)
+    if (!legacy.block)
         return primary;
     log("recall_legacy_peer_hit", { legacyPeerId });
-    return primary ? `${primary}\n${legacy}` : legacy;
+    return {
+        block: primary.block ? `${primary.block}\n${legacy.block}` : legacy.block,
+        contentCount: primary.contentCount + legacy.contentCount,
+        hintCount: primary.hintCount + legacy.hintCount,
+        budgetUsed: primary.budgetUsed + legacy.budgetUsed,
+        stage: primary.block ? primary.stage : legacy.stage,
+    };
+}
+/** The block alone, or null when nothing was injectable. */
+export async function buildRecallBlock(fetchJSON, cfg, query, options = {}) {
+    const { block } = await buildRecallBlockDetailed(fetchJSON, cfg, query, options);
+    return block || null;
+}
+function emptyRecall(stage) {
+    return { block: "", contentCount: 0, hintCount: 0, budgetUsed: 0, stage };
 }
 async function recallForPeer(fetchJSON, cfg, query, options = {}) {
     const actorPeerId = options.actorPeerId ?? cfg.peerId ?? "";
     const log = options.log || (() => { });
     const trimmed = String(query || "").trim();
     if (!trimmed)
-        return null;
+        return emptyRecall("no_results");
     // 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, {
@@ -621,13 +661,24 @@ async function recallForPeer(fetchJSON, cfg, query, options = {}) {
         actorPeerId,
         log,
     });
-    if (serverBlock !== null)
-        return serverBlock || null;
+    if (serverBlock !== null) {
+        if (!serverBlock)
+            return emptyRecall("no_results");
+        // The server rendered one budgeted unit, so nothing here degraded to a
+        // URI-only hint and the block's own estimate is what it cost.
+        return {
+            block: serverBlock,
+            contentCount: 1,
+            hintCount: 0,
+            budgetUsed: estimateTokens(serverBlock),
+            stage: "server_assembled",
+        };
+    }
     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;
+        return emptyRecall("no_results");
     const profile = buildQueryProfile(trimmed);
     const scoreThreshold = Number.isFinite(Number(cfg.scoreThreshold)) ? Number(cfg.scoreThreshold) : 0.35;
     const filtered = raw.filter((it) => clampScore(it.score) >= scoreThreshold);
@@ -640,6 +691,6 @@ async function recallForPeer(fetchJSON, cfg, query, options = {}) {
         items: picked.map((it) => ({ type: it._sourceType, uri: it.uri, score: clampScore(it.score) })),
     });
     if (picked.length === 0)
-        return null;
+        return emptyRecall("filtered_out");
     return buildFallbackInjectionBlock(fetchJSON, picked, cfg, actorPeerId, log);
 }

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.15",
   "displayName": "OpenViking",
   "description": "OpenClaw context-engine plugin — OpenViking AI memory, long-term memory, knowledge base, semantic search, RAG, context engine. 长期记忆 · 知识库 · 语义检索 · 上下文引擎",
   "type": "module",
@@ -42,7 +42,7 @@
   ],
   "scripts": {
     "build": "node -e \"require('node:fs').rmSync('dist', { recursive: true, force: true })\" && tsc -p tsconfig.build.json",
-    "prepack": "npm run build",
+    "prepack": "node ../memory-plugin-shared/sync.mjs && npm run build",
     "test": "vitest run",
     "typecheck": "tsc -p tsconfig.json",
     "test:watch": "vitest"

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}, ` +

package/shared/recall-core.d.mts

@@ -1,3 +1,6 @@
+// GENERATED FROM examples/memory-plugin-shared/lib. DO NOT EDIT.
+import type { OvHttpRequestOptions } from "./ov-http.mjs";
+
 export type ContextSearchBody = {
   query: string;
   mode: "context";
@@ -37,3 +40,42 @@ export function contextRequestTimeoutMs(
 ): number | undefined;
 
 export function normalizeContextEntry(entry?: unknown): NormalizedContextEntry;
+
+export type RecallFetchJSON = (
+  path: string,
+  init?: RequestInit,
+  options?: OvHttpRequestOptions,
+) => Promise<{ ok: boolean; status?: number; result?: any; error?: any }>;
+
+export type RecallOptions = {
+  actorPeerId?: string;
+  legacyPeerId?: string;
+  sessionId?: string;
+  log?: (stage: string, data?: any) => void;
+};
+
+export type DetailedRecall = {
+  block: string;
+  contentCount: number;
+  hintCount: number;
+  budgetUsed: number;
+  stage: "server_assembled" | "ranked" | "no_results" | "filtered_out";
+};
+
+export function buildRecallBlockDetailed(
+  fetchJSON: RecallFetchJSON,
+  cfg: Record<string, any>,
+  query: string,
+  options?: RecallOptions,
+): Promise<DetailedRecall>;
+
+export function buildRecallBlock(
+  fetchJSON: RecallFetchJSON,
+  cfg: Record<string, any>,
+  query: string,
+  options?: RecallOptions,
+): Promise<string | null>;
+
+export function buildRecallEndpointBody(cfg?: Record<string, any>): Record<string, any>;
+export function estimateTokens(text: string): number;
+export function isRecallEnabled(cfg?: Record<string, any>): boolean;

package/shared/recall-core.mjs

@@ -31,6 +31,28 @@ const CODING_QUOTA_WEIGHTS = {
 
 let userSpaceCache = "";
 
+/**
+ * Is recall on for this config?
+ *
+ * The switch has four spellings in the wild: a boolean `autoRecall`, opencode's
+ * `{ enabled }` object, dsh and pi's `syncTurns`, and the global `enabled`
+ * that turns the whole plugin off. Reading it here rather than in each loader
+ * is what keeps it from drifting a fifth time — and any spelling that says off
+ * wins, so a config that disables recall under an older name still disables it.
+ */
+export function isRecallEnabled(cfg = {}) {
+  return isSwitchOn([cfg.enabled, cfg.autoRecall, cfg.recall, cfg.syncRecall]);
+}
+
+/** Any recognised spelling that says off wins; everything else means on. */
+function isSwitchOn(values) {
+  for (const value of values) {
+    if (value === false) return false;
+    if (value && typeof value === "object" && !Array.isArray(value) && value.enabled === false) return false;
+  }
+  return true;
+}
+
 export function estimateTokens(text) {
   return text ? Math.ceil(String(text).length / 4) : 0;
 }
@@ -338,9 +360,8 @@ async function resolveItemContent(fetchJSON, item, cfg, actorPeerId = "") {
 }
 
 async function buildFallbackInjectionBlock(fetchJSON, items, cfg, actorPeerId = "", log = () => {}) {
-  if (items.length === 0) return null;
-
-  let budgetRemaining = Math.max(200, Number(cfg.recallTokenBudget || 2000));
+  const budgetTotal = Math.max(200, Number(cfg.recallTokenBudget || 2000));
+  let budgetRemaining = budgetTotal;
   const lines = [
     "<openviking-context>",
     "Relevant context from OpenViking. Use the read MCP tool to expand URIs.",
@@ -373,15 +394,15 @@ async function buildFallbackInjectionBlock(fetchJSON, items, cfg, actorPeerId =
 
   lines.push("</openviking-context>");
 
-  const budgetUsed = Math.max(200, Number(cfg.recallTokenBudget || 2000)) - budgetRemaining;
+  const budgetUsed = budgetTotal - budgetRemaining;
   log("recall_injection_built", {
     contentItems: contentCount,
     hintItems: hintCount,
     budgetUsed,
-    budgetTotal: Math.max(200, Number(cfg.recallTokenBudget || 2000)),
+    budgetTotal,
   });
 
-  return lines.join("\n");
+  return { block: lines.join("\n"), contentCount, hintCount, budgetUsed, stage: "ranked" };
 }
 
 const LEGACY_CACHE_TTL_MS = 6 * 60 * 60 * 1000;
@@ -626,8 +647,13 @@ export async function postRecall(fetchJSON, body, opts = {}) {
  * `"actor"` that sweep is off by definition, so the old peer is asked for
  * separately — as itself, which is both cheaper and wider than a bare
  * cross-peer read (that would need the user id, and reaches memories only).
+ *
+ * `stage` names the path the block came from, which is what a host needs to
+ * tell "the server had nothing" (`no_results`) from "the score threshold
+ * dropped everything" (`filtered_out`) when the block is empty, and a
+ * `server_assembled` block from a `ranked` one when it is not.
  */
-export async function buildRecallBlock(fetchJSON, cfg, query, options = {}) {
+export async function buildRecallBlockDetailed(fetchJSON, cfg, query, options = {}) {
   const primary = await recallForPeer(fetchJSON, cfg, query, options);
 
   const legacyPeerId = String(options.legacyPeerId || "").trim();
@@ -636,16 +662,32 @@ export async function buildRecallBlock(fetchJSON, cfg, query, options = {}) {
 
   const log = options.log || (() => {});
   const legacy = await recallForPeer(fetchJSON, cfg, query, { ...options, actorPeerId: legacyPeerId });
-  if (!legacy) return primary;
+  if (!legacy.block) return primary;
   log("recall_legacy_peer_hit", { legacyPeerId });
-  return primary ? `${primary}\n${legacy}` : legacy;
+  return {
+    block: primary.block ? `${primary.block}\n${legacy.block}` : legacy.block,
+    contentCount: primary.contentCount + legacy.contentCount,
+    hintCount: primary.hintCount + legacy.hintCount,
+    budgetUsed: primary.budgetUsed + legacy.budgetUsed,
+    stage: primary.block ? primary.stage : legacy.stage,
+  };
+}
+
+/** The block alone, or null when nothing was injectable. */
+export async function buildRecallBlock(fetchJSON, cfg, query, options = {}) {
+  const { block } = await buildRecallBlockDetailed(fetchJSON, cfg, query, options);
+  return block || null;
+}
+
+function emptyRecall(stage) {
+  return { block: "", contentCount: 0, hintCount: 0, budgetUsed: 0, stage };
 }
 
 async function recallForPeer(fetchJSON, cfg, query, options = {}) {
   const actorPeerId = options.actorPeerId ?? cfg.peerId ?? "";
   const log = options.log || (() => {});
   const trimmed = String(query || "").trim();
-  if (!trimmed) return null;
+  if (!trimmed) return emptyRecall("no_results");
 
   // Assembly happens server-side when the deployment offers the context face;
   // older servers fall through to /recall, then to raw find.
@@ -654,12 +696,23 @@ async function recallForPeer(fetchJSON, cfg, query, options = {}) {
     actorPeerId,
     log,
   });
-  if (serverBlock !== null) return serverBlock || null;
+  if (serverBlock !== null) {
+    if (!serverBlock) return emptyRecall("no_results");
+    // The server rendered one budgeted unit, so nothing here degraded to a
+    // URI-only hint and the block's own estimate is what it cost.
+    return {
+      block: serverBlock,
+      contentCount: 1,
+      hintCount: 0,
+      budgetUsed: estimateTokens(serverBlock),
+      stage: "server_assembled",
+    };
+  }
 
   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;
+  if (raw.length === 0) return emptyRecall("no_results");
 
   const profile = buildQueryProfile(trimmed);
   const scoreThreshold = Number.isFinite(Number(cfg.scoreThreshold)) ? Number(cfg.scoreThreshold) : 0.35;
@@ -673,6 +726,6 @@ async function recallForPeer(fetchJSON, cfg, query, options = {}) {
     items: picked.map((it) => ({ type: it._sourceType, uri: it.uri, score: clampScore(it.score) })),
   });
 
-  if (picked.length === 0) return null;
+  if (picked.length === 0) return emptyRecall("filtered_out");
   return buildFallbackInjectionBlock(fetchJSON, picked, cfg, actorPeerId, log);
 }