@openviking/openclaw-plugin 2026.9.1 → 2026.9.4

package/README.md

@@ -164,16 +164,9 @@ During recall, the plugin:
 1. Extracts query text from the latest user message.
 2. Resolves the agent routing for the current `sessionId/sessionKey`.
 3. Runs a quick availability precheck so model requests do not stall when OpenViking is unavailable.
-4. Queries the configured `recallTargetTypes` (`user,agent` by default; optionally `resource`; use `ov_archive_search` and `ov_archive_expand` for session history).
-5. Deduplicates, threshold-filters, reranks, and trims the results under a token budget.
-6. Prepends the selected memories as a `## Long-term Memories` section inside `<openviking-context>` to the current user message; it does not append a standalone synthetic user message.
-
-The reranking logic is not pure vector-score sorting. The current implementation also considers:
-
-- whether a result is a leaf memory with `level == 2`
-- whether it looks like a preference memory
-- whether it looks like an event memory
-- lexical overlap with the current query
+4. Sends one session-aware context search for the configured `recallTargetTypes` (`user,agent` by default; optionally `resource`; use `ov_archive_search` and `ov_archive_expand` to inspect raw session history).
+5. Lets OpenViking expand the query from session history, filter and rank candidates, apply cross-turn deduplication, select detail tiers, and assemble the result under the injection budget.
+6. Prepends the server-rendered context inside `<relevant-memories>` to the current user message; it does not append a standalone synthetic user message.
 
 ## Session Lifecycle
 

package/auto-recall.ts

@@ -1,12 +1,7 @@
-import type { FindResult, FindResultItem, OpenVikingClient } from "./client.js";
+import type { FindResultItem, OpenVikingClient, SearchContextEntry } from "./client.js";
 import type { MemoryOpenVikingConfig } from "./config.js";
 import type { EffectiveQueryConfig } from "./query-config.js";
-import {
-  pickMemoriesForInjection,
-  postProcessMemories,
-  summarizeInjectionMemories,
-  toJsonLog,
-} from "./memory-ranking.js";
+import { toJsonLog } from "./memory-ranking.js";
 import { quickRecallPrecheck, withTimeout } from "./process-manager.js";
 import {
   resolveRecallSearchPlan,
@@ -20,6 +15,8 @@ import { sanitizeUserTextForCapture } from "./text-utils.js";
 import { estimateTextTokens } from "./token-estimator.js";
 
 const RECALL_QUERY_MAX_CHARS = 4_000;
+const AUTO_RECALL_DEDUP_TURNS = 5;
+const LEGACY_CHARS_PER_TOKEN = 4;
 export const AUTO_RECALL_SOURCE_MARKER = "Source: openviking-auto-recall";
 
 type Logger = {
@@ -231,16 +228,26 @@ function preview(value: string | undefined, maxChars: number): string | undefine
   return trimmed.length > maxChars ? trimmed.slice(0, maxChars) : trimmed;
 }
 
-function toTraceResults(items: FindResultItem[], resourceType: RecallResourceType): RecallTraceResult[] {
-  return items.map((item) => ({
-    uri: item.uri,
+function traceResourceType(entry: SearchContextEntry): RecallResourceType {
+  if (entry.category === "resources" || entry.uri.startsWith("viking://resources")) {
+    return "resource";
+  }
+  if (entry.origin === "actor_peer") {
+    return "agent";
+  }
+  return "user";
+}
+
+function toTraceResult(entry: SearchContextEntry): RecallTraceResult {
+  const resourceType = traceResourceType(entry);
+  return {
+    uri: entry.uri,
     resourceType,
-    category: item.category,
-    score: item.score,
-    level: item.level,
-    abstractPreview: preview(item.abstract ?? item.overview, 240),
+    category: entry.category,
+    score: entry.score,
+    abstractPreview: preview(entry.text, 240),
     resultType: resourceType === "resource" ? "resource" : "memory",
-  }));
+  };
 }
 
 function boundTraceQuery(query: string, maxChars: number): { query: string; queryTruncated?: boolean } {
@@ -340,7 +347,6 @@ export async function buildAutoRecallContext(params: {
 
   return withTimeout(
     (async () => {
-      const candidateLimit = queryConfig?.candidateLimit ?? Math.max(cfg.recallLimit * 4, 20);
       const scoreThreshold = queryConfig?.scoreThreshold ?? cfg.recallScoreThreshold;
       const recallLimit = queryConfig?.recallLimit ?? cfg.recallLimit;
       const maxInjectedChars = queryConfig?.maxInjectedChars ?? cfg.recallMaxInjectedChars;
@@ -349,98 +355,88 @@ export async function buildAutoRecallContext(params: {
         ovSessionId: params.ovSessionId,
         agentId,
       });
-      const traceSearches: RecallTraceEntry["searches"] = searchPlan.skipped.map((skipped) => ({
-        resourceType: skipped.resourceType,
-        limit: candidateLimit,
-        scoreThreshold: 0,
-        durationMs: 0,
-        total: 0,
-        results: [],
-        error: skipped.reason,
-      }));
-      const autoRecallPromises: Promise<{
-        resourceType: RecallResourceType;
-        targetUri?: string;
-        result?: FindResult;
-        durationMs: number;
-      }>[] = searchPlan.searches.map(async (search) => {
-        const start = Date.now();
-        const result = await client.find(queryText, {
-          targetUri: search.targetUri,
-          limit: candidateLimit,
-          scoreThreshold: 0,
-          contextType: search.contextType,
+      const contextTypes = [...new Set(searchPlan.searches.map((search) => search.contextType))];
+      const maxTokens = Math.min(
+        32_000,
+        Math.max(64, Math.round(maxInjectedChars / LEGACY_CHARS_PER_TOKEN)),
+      );
+      const startedAt = Date.now();
+      let contextResult: Awaited<ReturnType<OpenVikingClient["searchContext"]>> | undefined;
+      let requestError: unknown;
+
+      try {
+        contextResult = await client.searchContext(queryText, {
+          sessionId: params.ovSessionId,
+          limit: recallLimit,
+          scoreThreshold,
+          contextType: contextTypes.length === 1 ? contextTypes[0] : contextTypes,
+          queryExpansion: "auto",
+          maxTokens,
+          detail: recallPreferAbstract ? "abstract" : undefined,
+          dedupTurns: params.ovSessionId ? AUTO_RECALL_DEDUP_TURNS : undefined,
+          peerScope: "actor",
           actorPeerId,
+          requestTimeoutMs: cfg.autoRecallTimeoutMs,
         });
-        return {
-          resourceType: search.resourceType,
-          targetUri: search.targetUri,
-          result,
-          durationMs: Date.now() - start,
-        };
-      });
-      const autoRecallSettled = await Promise.allSettled(autoRecallPromises);
-
-      const allMemories: FindResultItem[] = [];
-      for (const s of autoRecallSettled) {
-        if (s.status === "fulfilled") {
-          const result = s.value.result ?? {};
-          const memories = result.memories ?? [];
-          const resources = result.resources ?? [];
-          allMemories.push(...memories, ...resources);
-          traceSearches.push({
-            resourceType: s.value.resourceType,
-            targetUriInput: s.value.targetUri,
-            limit: candidateLimit,
-            scoreThreshold: 0,
-            durationMs: s.value.durationMs,
-            total: result.total ?? memories.length + resources.length + (result.skills?.length ?? 0),
-            results: [
-              ...toTraceResults(memories, s.value.resourceType),
-              ...toTraceResults(resources, "resource"),
-              ...(result.skills ?? []).map((item): RecallTraceResult => ({
-                uri: item.uri,
-                resourceType: s.value.resourceType,
-                category: item.category,
-                score: item.score,
-                level: item.level,
-                abstractPreview: preview(item.abstract ?? item.overview, 240),
-                resultType: "skill",
-              })),
-            ].slice(0, cfg.traceRecallMaxResultsPerSearch),
-          });
-        } else {
-          logger.warn?.(`openviking: auto-recall search failed: ${String(s.reason)}`);
-          const failedIndex = traceSearches.length;
-          const search = searchPlan.searches[failedIndex - searchPlan.skipped.length];
-          traceSearches.push({
-            resourceType: search?.resourceType ?? "user",
-            targetUriInput: search?.targetUri,
-            limit: candidateLimit,
-            scoreThreshold: 0,
-            durationMs: 0,
-            total: 0,
-            results: [],
-            error: String(s.reason),
-          });
-        }
+      } catch (error) {
+        requestError = error;
       }
 
-      const uniqueMemories = allMemories.filter((memory, index, self) =>
-        index === self.findIndex((m) => m.uri === memory.uri)
-      );
-      const leafOnly = uniqueMemories.filter((m) => !m.level || m.level === 2);
-      const processed = postProcessMemories(leafOnly, {
-        limit: candidateLimit,
-        scoreThreshold,
-      });
-      const memories = pickMemoriesForInjection(processed, recallLimit, queryText, scoreThreshold, queryConfig ? {
-        weights: queryConfig.rankingWeights,
-        categoryWeights: queryConfig.categoryWeights,
-        resourceTypeWeights: queryConfig.resourceTypeWeights,
-      } : undefined);
+      const durationMs = Date.now() - startedAt;
+      const entries = (contextResult?.entries ?? []).filter((entry) => Boolean(entry.uri));
+      const rawRetrievalErrors = contextResult?.stats?.retrieval_errors;
+      const retrievalErrors = Array.isArray(rawRetrievalErrors)
+        ? rawRetrievalErrors.map((error) => String(error))
+        : [];
+      const searchError = requestError
+        ? String(requestError)
+        : retrievalErrors.length > 0
+          ? retrievalErrors.join("; ")
+          : undefined;
+
+      if (searchError) {
+        logger.warn?.(`openviking: auto-recall context search failed: ${searchError}`);
+      }
 
-      const recordTrace = async (injectedMemories: FindResultItem[], injectedCount: number, estimatedTokens?: number) => {
+      const traceSearches: RecallTraceEntry["searches"] = [
+        ...searchPlan.skipped.map((skipped) => ({
+          resourceType: skipped.resourceType,
+          limit: recallLimit,
+          scoreThreshold,
+          durationMs: 0,
+          total: 0,
+          results: [],
+          error: skipped.reason,
+        })),
+        ...searchPlan.searches.map((search) => {
+          const matchingEntries = entries.filter((entry) =>
+            search.contextType === "resource"
+              ? traceResourceType(entry) === "resource"
+              : traceResourceType(entry) !== "resource"
+          );
+          return {
+            resourceType: search.resourceType,
+            contextType: search.contextType,
+            limit: recallLimit,
+            scoreThreshold,
+            durationMs,
+            total: matchingEntries.length,
+            results: matchingEntries
+              .map(toTraceResult)
+              .slice(0, cfg.traceRecallMaxResultsPerSearch),
+            error: searchError,
+          };
+        }),
+      ];
+
+      const candidateCount = typeof contextResult?.stats?.candidates === "number"
+        ? contextResult.stats.candidates
+        : entries.length;
+      const recordTrace = async (
+        injectedEntries: SearchContextEntry[],
+        injectedCount: number,
+        estimatedTokens?: number,
+      ) => {
         const entry: RecallTraceEntry = {
           schemaVersion: "1.0",
           traceId: newTraceId(),
@@ -459,17 +455,17 @@ export async function buildAutoRecallContext(params: {
             queryTruncated: params.queryTruncated || queryText.length > cfg.traceRecallQueryMaxChars,
           },
           searches: traceSearches,
-          selected: injectedMemories.map((memory) => ({
-            uri: memory.uri,
-            resourceType: memory.uri.startsWith("viking://resources") ? "resource" : undefined,
-            category: memory.category,
-            score: memory.score,
-            abstractPreview: preview(memory.abstract ?? memory.overview, cfg.traceRecallPreviewChars),
+          selected: injectedEntries.map((contextEntry) => ({
+            uri: contextEntry.uri,
+            resourceType: traceResourceType(contextEntry),
+            category: contextEntry.category,
+            score: contextEntry.score,
+            abstractPreview: preview(contextEntry.text, cfg.traceRecallPreviewChars),
             injected: true,
           })),
           stats: {
-            candidateCount: allMemories.length,
-            selectedCount: injectedMemories.length,
+            candidateCount,
+            selectedCount: injectedEntries.length,
             injectedCount,
             estimatedTokens,
           },
@@ -478,39 +474,34 @@ export async function buildAutoRecallContext(params: {
         params.traceRecorder?.record(entry);
       };
 
-      if (memories.length === 0) {
-        await recordTrace([], 0, 0);
-        return { memoryCount: 0, estimatedTokens: 0 };
-      }
-
-      const { lines: memoryLines, estimatedTokens } = await buildMemoryLinesWithBudget(
-        memories,
-        (uri) => client.read(uri, actorPeerId),
-        {
-          recallPreferAbstract,
-          recallMaxInjectedChars: maxInjectedChars,
-          includeUri: true,
-        },
-      );
-
-      if (memoryLines.length === 0) {
-        verbose?.(
-          `openviking: skipping auto-recall injection; no complete memories fit maxInjectedChars=${maxInjectedChars}`,
-        );
+      const rendered = contextResult?.rendered?.trim() ?? "";
+      if (requestError || entries.length === 0 || !rendered) {
         await recordTrace([], 0, 0);
         return { memoryCount: 0, estimatedTokens: 0 };
       }
 
-      const block = buildRecallContextBlock(memoryLines);
+      const usedTokens = contextResult?.stats?.used_tokens;
+      const estimatedTokens = typeof usedTokens === "number" && Number.isFinite(usedTokens)
+        ? Math.max(0, Math.ceil(usedTokens))
+        : estimateTokenCount(rendered);
+      const block = buildRecallContextBlock([rendered]);
       verbose?.(
-        `openviking: injecting ${memoryLines.length} memories (${block.length} chars, ~${estimatedTokens} tokens, maxInjectedChars=${maxInjectedChars})`,
+        `openviking: injecting ${entries.length} memories (${block.length} chars, ~${estimatedTokens} tokens, serverMaxTokens=${maxTokens})`,
       );
       verbose?.(
-        `openviking: inject-detail ${toJsonLog({ count: memories.length, memories: summarizeInjectionMemories(memories) })}`,
+        `openviking: inject-detail ${toJsonLog({
+          count: entries.length,
+          entries: entries.map((contextEntry) => ({
+            uri: contextEntry.uri,
+            category: contextEntry.category,
+            score: contextEntry.score,
+            detail: contextEntry.detail,
+          })),
+        })}`,
       );
 
-      await recordTrace(memories.slice(0, memoryLines.length), memoryLines.length, estimatedTokens);
-      return { block, memoryCount: memoryLines.length, estimatedTokens };
+      await recordTrace(entries, entries.length, estimatedTokens);
+      return { block, memoryCount: entries.length, estimatedTokens };
     })(),
     cfg.autoRecallTimeoutMs,
     "openviking: auto-recall search timeout",

package/client.ts

@@ -12,6 +12,11 @@ import {
   defaultResourcePackager,
   type ResourcePackager,
 } from "./adapters/resource-packager.js";
+import {
+  buildContextSearchBody,
+  contextRequestTimeoutMs,
+  normalizeContextEntry,
+} from "./shared/recall-core.mjs";
 
 export type FindResultItem = {
   uri: string;
@@ -30,6 +35,36 @@ export type FindResult = {
   total?: number;
 };
 
+export type SearchContextEntry = {
+  uri: string;
+  category?: string;
+  score?: number;
+  detail?: string;
+  text?: string;
+  origin?: string;
+};
+
+export type SearchContextResult = {
+  entries?: SearchContextEntry[];
+  rendered?: string;
+  digest?: string;
+  stats?: Record<string, unknown>;
+};
+
+export type SearchContextOptions = {
+  sessionId?: string;
+  limit?: number;
+  scoreThreshold?: number;
+  contextType?: string | string[];
+  queryExpansion?: "off" | "auto";
+  maxTokens?: number;
+  detail?: "abstract" | "overview" | "full";
+  dedupTurns?: number;
+  peerScope?: "actor" | "all";
+  actorPeerId?: string;
+  requestTimeoutMs?: number;
+};
+
 export type FsListEntry = string | Record<string, unknown>;
 
 export type FsListResult = FsListEntry[];
@@ -488,6 +523,66 @@ export class OpenVikingClient {
     }, undefined, actorPeerId);
   }
 
+  async searchContext(
+    query: string,
+    options: SearchContextOptions = {},
+  ): Promise<SearchContextResult> {
+    const contractConfig = {
+      recallLimit: options.limit,
+      recallLimitConfigured: options.limit !== undefined,
+      recallMaxTokens: options.maxTokens,
+      recallMaxTokensConfigured: options.maxTokens !== undefined,
+      scoreThreshold: options.scoreThreshold,
+      recallQueryExpansion: options.queryExpansion,
+      recallQueryExpansionConfigured: options.queryExpansion !== undefined,
+      recallDedupTurns: options.dedupTurns,
+      recallPeerScope: options.peerScope,
+      recallContextTimeoutMs: options.requestTimeoutMs,
+      timeoutMs: this.timeoutMs,
+    };
+    const body = {
+      ...buildContextSearchBody(contractConfig, { sessionId: options.sessionId }),
+      query,
+      ...(options.contextType !== undefined ? { context_type: options.contextType } : {}),
+      ...(options.detail !== undefined ? { detail: options.detail } : {}),
+    };
+    const requestTimeoutMs = contextRequestTimeoutMs(contractConfig, body);
+    const actorPeerId = this.resolveActorPeerHeader(options.actorPeerId);
+    const tenantHeaders = this.resolveTenantHeaders();
+    this.routingDebugLog?.(
+      `openviking: context search POST ${this.baseUrl}/api/v1/search/search ` +
+        JSON.stringify({
+          X_OpenViking_Account: tenantHeaders.accountId ?? null,
+          X_OpenViking_User: tenantHeaders.userId ?? null,
+          X_OpenViking_Actor_Peer: actorPeerId ?? null,
+          session_id: body.session_id ?? null,
+          query:
+            query.length > 4000
+              ? `${query.slice(0, 4000)}…(+${query.length - 4000} more chars)`
+              : query,
+          purpose: body.purpose,
+          quotas: body.quotas ?? null,
+          score_threshold: body.score_threshold,
+          context_type: body.context_type ?? null,
+          query_expansion: body.query_expansion ?? null,
+          max_tokens: body.max_tokens ?? null,
+          detail: body.detail ?? null,
+          dedup_turns: body.dedup_turns ?? 0,
+          peer_scope: body.peer_scope ?? null,
+        }),
+    );
+    const result = await this.request<SearchContextResult>("/api/v1/search/search", {
+      method: "POST",
+      body: JSON.stringify(body),
+    }, requestTimeoutMs, actorPeerId);
+    return {
+      ...result,
+      entries: Array.isArray(result.entries)
+        ? result.entries.map((entry) => ({ ...entry, ...normalizeContextEntry(entry) }))
+        : result.entries,
+    };
+  }
+
   async read(uri: string, actorPeerId?: string): Promise<string> {
     return this.request<string>(
       `/api/v1/content/read?uri=${encodeURIComponent(uri)}`,

package/config.ts

@@ -45,13 +45,13 @@ export type MemoryOpenVikingConfig = {
   captureMode?: "semantic" | "keyword";
   captureMaxLength?: number;
   autoRecall?: boolean;
-  /** Outer time budget for the whole auto-recall flow, including search, ranking, and reads. */
+  /** Outer time budget for the whole server-assembled auto-recall flow. */
   autoRecallTimeoutMs?: number;
   /** Include resources in auto-recall and default memory_recall search. Default false. */
   recallResources?: boolean;
   recallLimit?: number;
   recallScoreThreshold?: number;
-  /** Maximum total characters injected by auto-recall. */
+  /** Legacy character budget, converted to the server context token budget. */
   recallMaxInjectedChars?: number;
   /** @deprecated Auto-recall no longer truncates individual memories. */
   recallMaxContentChars?: number;
@@ -140,7 +140,9 @@ const DEFAULT_TARGET_URI = "viking://~/memories";
 const DEFAULT_TIMEOUT_MS = 15000;
 const DEFAULT_CAPTURE_MODE = "semantic";
 const DEFAULT_CAPTURE_MAX_LENGTH = 24000;
-const DEFAULT_AUTO_RECALL_TIMEOUT_MS = 5000;
+// Session-aware context search may spend up to 5 seconds on query expansion
+// before returning its server-side fallback, so leave headroom for retrieval.
+const DEFAULT_AUTO_RECALL_TIMEOUT_MS = 15000;
 const DEFAULT_RECALL_LIMIT = 6;
 const DEFAULT_RECALL_SCORE_THRESHOLD = 0.15;
 const DEFAULT_RECALL_MAX_CONTENT_CHARS = 5000;
@@ -843,7 +845,7 @@ export const memoryOpenVikingConfigSchema = {
       label: "Auto-Recall Timeout (ms)",
       placeholder: String(DEFAULT_AUTO_RECALL_TIMEOUT_MS),
       advanced: true,
-      help: "Outer time budget for the whole auto-recall flow, including search, ranking, and memory reads.",
+      help: "Outer time budget for the server-assembled context search, including session-aware query expansion.",
     },
     recallResources: {
       label: "Recall Resources",
@@ -870,7 +872,7 @@ export const memoryOpenVikingConfigSchema = {
       label: "Recall Max Injected Chars",
       placeholder: String(DEFAULT_RECALL_MAX_INJECTED_CHARS),
       advanced: true,
-      help: "Maximum total characters for auto-recall memory injection. Complete memories that do not fit are skipped, not truncated.",
+      help: "Legacy auto-recall character budget. It is converted to the server context token budget at four characters per token.",
     },
     recallMaxContentChars: {
       label: "Deprecated Recall Max Content Chars",
@@ -881,7 +883,7 @@ export const memoryOpenVikingConfigSchema = {
     recallPreferAbstract: {
       label: "Recall Prefer Abstract",
       advanced: true,
-      help: "Use memory abstract instead of fetching full content when abstract is available. Reduces token usage.",
+      help: "Pin server-assembled auto-recall entries to abstract detail. When disabled, the server chooses each category's default detail tier.",
     },
     recallTokenBudget: {
       label: "Deprecated Recall Token Budget",