Self-evolving Context Database for AI Agents. Unify Agent Memory, Knowledge RAG and Skills.
Python agent-contextagent-memoryagent-pluginsagentic-ragcontext-databasedsh-pluginknowledge-basememorymemory-managementself-evolvingvector-database
feat(openclaw): wire recall trace runtime (#2589)
Mingjian Qued497b05aee92
diff --git a/examples/openclaw-plugin/auto-recall.ts b/examples/openclaw-plugin/auto-recall.tsindex a98b839b4..a05c45977 100644--- a/examples/openclaw-plugin/auto-recall.ts+++ b/examples/openclaw-plugin/auto-recall.ts@@ -9,6 +9,11 @@ import {import { quickRecallPrecheck, withTimeout } from "./process-manager.js";import { sanitizeUserTextForCapture } from "./text-utils.js";import { estimateTextTokens } from "./token-estimator.js";+import type {+ RecallResourceType,+ RecallTraceEntry,+ RecallTraceResult,+} from "./recall-trace.js";const RECALL_QUERY_MAX_CHARS = 4_000;export const AUTO_RECALL_SOURCE_MARKER = "Source: openviking-auto-recall";@@ -239,6 +244,40 @@ export function buildOpenVikingContextBlock(params: {].join("\n");}+function newTraceId(): string {+ return `auto_recall_${Date.now().toString(36)}_${Math.random().toString(36).slice(2, 10)}`;+}++function preview(value: string | undefined | null, maxChars: number): string | undefined {+ const normalized = typeof value === "string" ? value.trim().replace(/\s+/g, " ") : "";+ if (!normalized) {+ return undefined;+ }+ return normalized.length > maxChars ? normalized.slice(0, maxChars) : normalized;+}++function traceResourceTypeForUri(uri: string | undefined): RecallResourceType {+ return uri?.startsWith("viking://resources") ? "resource" : "user";+}++function toTraceResults(items: FindResultItem[], resourceType: RecallResourceType): RecallTraceResult[] {+ return items.map((item) => ({+ uri: item.uri,+ resourceType,+ category: item.category,+ score: item.score,+ level: item.level,+ abstractPreview: preview(item.abstract ?? item.overview, 240),+ resultType: resourceType === "resource" ? "resource" : "memory",+ }));+}++function boundTraceQuery(query: string, maxChars: number): { query: string; queryTruncated?: boolean } {+ return query.length <= maxChars+ ? { query }+ : { query: query.slice(0, maxChars), queryTruncated: true };+}+function runtimeFlag(runtimeContext: unknown, key: string): unknown {return runtimeContext && typeof runtimeContext === "object"? (runtimeContext as Record<string, unknown>)[key]@@ -471,6 +510,12 @@ export async function buildLongTermMemoryRecallContext(params: {queryText: string;logger: Logger;verbose?: (message: string) => void;+ traceRecorder?: { record(entry: RecallTraceEntry): void };+ sessionId?: string;+ sessionKey?: string;+ ovSessionId?: string;+ rawUserTextPreview?: string;+ queryTruncated?: boolean;}): Promise<{ section?: string; memoryCount: number; estimatedTokens: number }> {const { cfg, client, agentId, peerId, queryText, logger, verbose } = params;@@ -487,32 +532,72 @@ export async function buildLongTermMemoryRecallContext(params: {return withTimeout((async () => {const candidateLimit = Math.max(cfg.recallLimit * 4, 20);- const autoRecallPromises: Promise<FindResult>[] = [- client.find(queryText, {- targetUri: "viking://user/memories",+ const targetUris = [+ "viking://user/memories",+ ...(cfg.recallResources ? ["viking://resources"] : []),+ ];+ const autoRecallPromises = targetUris.map(async (targetUri) => {+ const started = Date.now();+ const result = await client.find(queryText, {+ targetUri,limit: candidateLimit,scoreThreshold: 0,peerId,- }, agentId),- ];- if (cfg.recallResources) {- autoRecallPromises.push(- client.find(queryText, {- targetUri: "viking://resources",- limit: candidateLimit,- scoreThreshold: 0,- peerId,- }, agentId),- );- }+ }, agentId);+ return {+ targetUri,+ result,+ durationMs: Date.now() - started,+ };+ });+ const traceSearches: RecallTraceEntry["searches"] = [];const autoRecallSettled = await Promise.allSettled(autoRecallPromises);const allMemories: FindResultItem[] = [];- for (const s of autoRecallSettled) {+ for (let index = 0; index < autoRecallSettled.length; index += 1) {+ const s = autoRecallSettled[index]!;+ const targetUri = targetUris[index]!;+ const resourceType = traceResourceTypeForUri(targetUri);if (s.status === "fulfilled") {- allMemories.push(...(s.value.memories ?? []), ...(s.value.resources ?? []));+ const result = s.value.result;+ const memories = result.memories ?? [];+ const resources = result.resources ?? [];+ allMemories.push(...memories, ...resources);+ traceSearches.push({+ resourceType,+ targetUriInput: targetUri,+ targetUriResolved: targetUri,+ limit: candidateLimit,+ scoreThreshold: 0,+ durationMs: s.value.durationMs,+ total: result.total ?? memories.length + resources.length + (result.skills?.length ?? 0),+ results: [+ ...toTraceResults(memories, resourceType),+ ...toTraceResults(resources, "resource"),+ ...(result.skills ?? []).map((item): RecallTraceResult => ({+ uri: item.uri,+ 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)}`);+ traceSearches.push({+ resourceType,+ targetUriInput: targetUri,+ targetUriResolved: targetUri,+ limit: candidateLimit,+ scoreThreshold: 0,+ durationMs: 0,+ total: 0,+ results: [],+ error: String(s.reason),+ });}}@@ -525,8 +610,46 @@ export async function buildLongTermMemoryRecallContext(params: {scoreThreshold: cfg.recallScoreThreshold,});const memories = pickMemoriesForInjection(processed, cfg.recallLimit, queryText);+ const resourceTypes = [...new Set(traceSearches+ .map((search) => search.resourceType)+ .filter((resourceType): resourceType is RecallResourceType => resourceType !== "archive"))];+ const recordTrace = (injectedMemories: FindResultItem[], injectedCount: number, estimatedTokens?: number) => {+ params.traceRecorder?.record({+ schemaVersion: "1.0",+ traceId: newTraceId(),+ ts: Date.now(),+ sessionId: params.sessionId,+ sessionKey: params.sessionKey,+ ovSessionId: params.ovSessionId,+ agentId,+ source: "auto_recall",+ operationType: "semantic_find",+ resourceTypes: resourceTypes.length > 0 ? resourceTypes : ["user"],+ trigger: {+ rawUserTextPreview: params.rawUserTextPreview,+ ...boundTraceQuery(queryText, cfg.traceRecallQueryMaxChars),+ queryTruncated: params.queryTruncated || queryText.length > cfg.traceRecallQueryMaxChars,+ },+ searches: traceSearches,+ selected: injectedMemories.map((memory) => ({+ uri: memory.uri,+ resourceType: traceResourceTypeForUri(memory.uri),+ category: memory.category,+ score: memory.score,+ abstractPreview: preview(memory.abstract ?? memory.overview, cfg.traceRecallPreviewChars),+ injected: true,+ })),+ stats: {+ candidateCount: allMemories.length,+ selectedCount: injectedMemories.length,+ injectedCount,+ estimatedTokens,+ },+ });+ };if (memories.length === 0) {+ recordTrace([], 0, 0);return { memoryCount: 0, estimatedTokens: 0 };}@@ -544,6 +667,7 @@ export async function buildLongTermMemoryRecallContext(params: {verbose?.(`openviking: skipping auto-recall injection; no complete memories fit maxInjectedChars=${cfg.recallMaxInjectedChars}`,);+ recordTrace([], 0, 0);return { memoryCount: 0, estimatedTokens: 0 };}@@ -555,6 +679,7 @@ export async function buildLongTermMemoryRecallContext(params: {`openviking: inject-detail ${toJsonLog({ count: memories.length, memories: summarizeInjectionMemories(memories) })}`,);+ recordTrace(memories.slice(0, memoryLines.length), memoryLines.length, estimatedTokens);return { section, memoryCount: memoryLines.length, estimatedTokens };})(),cfg.autoRecallTimeoutMs,diff --git a/examples/openclaw-plugin/config.ts b/examples/openclaw-plugin/config.tsindex 768634f87..c03e5467c 100644--- a/examples/openclaw-plugin/config.ts+++ b/examples/openclaw-plugin/config.ts@@ -126,6 +126,7 @@ export const OPENVIKING_DEFAULT_ENABLED_TOOL_NAMES = ["ov_multi_read","ov_list","memory_recall",+ "ov_recall_trace","memory_store","memory_forget","ov_archive_search",@@ -145,6 +146,7 @@ export const OPENVIKING_TOOL_GROUPS: Record<string, readonly OpenVikingToolName[memory: ["memory_recall", "memory_store", "memory_forget"],resource_query: ["ov_search", "ov_read", "ov_multi_read", "ov_list"],import: ["add_resource", "add_skill"],+ recall_trace: ["ov_recall_trace"],archive: ["ov_archive_search", "ov_archive_expand"],tool_result: ["openviking_tool_result_read",@@ -743,7 +745,7 @@ export const memoryOpenVikingConfigSchema = {enabledTools: {label: "Enabled Tools",placeholder: "default",- help: "Agent-visible tool allowlist. Accepts tool names or groups: default, all, memory, resource_query, import, archive, tool_result. add_resource also requires enableAddResourceTool=true.",+ help: "Agent-visible tool allowlist. Accepts tool names or groups: default, all, memory, resource_query, import, recall_trace, archive, tool_result. add_resource also requires enableAddResourceTool=true.",advanced: true,},disabledTools: {diff --git a/examples/openclaw-plugin/context-engine.ts b/examples/openclaw-plugin/context-engine.tsindex c63753373..28c8ec33b 100644--- a/examples/openclaw-plugin/context-engine.ts+++ b/examples/openclaw-plugin/context-engine.ts@@ -20,6 +20,7 @@ import {trimForLog,toJsonLog,} from "./memory-ranking.js";+import type { RecallTraceEntry } from "./recall-trace.js";import { sanitizeToolUseResultPairing } from "./session-transcript-repair.js";import {estimateAgentMessageTokens,@@ -1092,6 +1093,7 @@ export function createMemoryOpenVikingContextEngine(params: {sessionKey?: string;ovSessionId?: string;}) => void;+ traceRecorder?: { record(entry: RecallTraceEntry): void };}): ContextEngineWithCommit {const {id,@@ -1102,6 +1104,7 @@ export function createMemoryOpenVikingContextEngine(params: {getClient,resolveAgentId,rememberSessionAgentId,+ traceRecorder,} = params;const diagEnabled = cfg.emitStandardDiagnostics;@@ -1428,6 +1431,12 @@ export function createMemoryOpenVikingContextEngine(params: {queryText: recallQuery.query,logger,verbose: (message) => logger.info(message),+ traceRecorder,+ sessionId: assembleParams.sessionId,+ sessionKey,+ ovSessionId: OVSessionId,+ rawUserTextPreview: recallQuery.query,+ queryTruncated: recallQuery.truncated,}): { memoryCount: 0, estimatedTokens: 0 };const longTermRecallWithQuery: AssembleRecall = { ...longTermRecall, queryChars: recallQuery.finalChars };diff --git a/examples/openclaw-plugin/index.ts b/examples/openclaw-plugin/index.tsindex 426c8b4a2..ef5458a08 100644--- a/examples/openclaw-plugin/index.ts+++ b/examples/openclaw-plugin/index.ts@@ -43,6 +43,15 @@ import {estimateTokenCount,prepareRecallQuery,} from "./auto-recall.js";+import {+ RecallTraceRecorder,+ normalizeResourceTypes,+ type RecallResourceType,+ type RecallTraceEntry,+ type RecallTraceQuery,+ type RecallTraceResult,+ type RecallTraceSource,+} from "./recall-trace.js";export {buildMemoryLines,buildMemoryLinesWithBudget,@@ -177,6 +186,20 @@ type OVMultiReadInput = {uris: string[];};+type RecallTraceToolInput = {+ turn?: "latest" | "all";+ traceId?: string;+ sessionId?: string;+ sessionKey?: string;+ ovSessionId?: string;+ source?: RecallTraceSource;+ resourceTypes?: RecallResourceType[] | string;+ since?: number;+ until?: number;+ includeContent?: boolean;+ limit?: number;+};+type ToolResultRef = {sessionId: string;toolResultId: string;@@ -253,6 +276,18 @@ type OpenClawPluginApi = {) => void;};+type RecallTraceRouteAdapter = {+ registerRoute?: (route: {+ method: "GET";+ path: string;+ handler: (request?: {+ query?: Record<string, unknown>;+ params?: Record<string, unknown>;+ url?: string;+ }) => Promise<unknown>;+ }) => void;+};+const DEFAULT_OPENCLAW_AGENT_ID = "main";/**@@ -381,6 +416,43 @@ function getBoolFlag(flags: Map<string, string | boolean>, name: string): booleareturn flags.get(name) === true;}+function createTraceId(source: RecallTraceSource): string {+ return `${source}_${Date.now().toString(36)}_${Math.random().toString(36).slice(2, 10)}`;+}++function previewText(value: string | undefined | null, maxChars: number): string | undefined {+ const normalized = typeof value === "string" ? value.trim().replace(/\s+/g, " ") : "";+ if (!normalized) {+ return undefined;+ }+ return normalized.length > maxChars ? normalized.slice(0, maxChars) : normalized;+}++function boundTraceQuery(query: string, maxChars: number): { query: string; queryTruncated?: boolean } {+ return query.length <= maxChars+ ? { query }+ : { query: query.slice(0, maxChars), queryTruncated: true };+}++function inferRecallResourceType(uri: string | undefined): RecallResourceType | undefined {+ if (!uri) {+ return undefined;+ }+ if (uri.startsWith("viking://resources")) {+ return "resource";+ }+ if (uri.startsWith("viking://session/") || uri.includes("/sessions/")) {+ return "session";+ }+ if (uri.startsWith("viking://agent/")) {+ return "agent";+ }+ if (uri.startsWith("viking://user/")) {+ return "user";+ }+ return undefined;+}+function extractToolSenderId(ctx: unknown): string | undefined {if (!ctx || typeof ctx !== "object") {return undefined;@@ -681,6 +753,17 @@ const contextEnginePlugin = {const getClient = (): Promise<OpenVikingClient> => clientPromise;+ const traceRecorder = cfg.traceRecall+ ? new RecallTraceRecorder({+ memoryMaxEntries: cfg.traceRecallMaxEntries,+ persist: cfg.traceRecallPersist,+ traceDir: cfg.traceRecallDir,+ includeRawUserPreview: cfg.traceRecallIncludeRawUserPreview,+ retentionDays: cfg.traceRecallRetentionDays,+ queryMaxDays: cfg.traceRecallQueryMaxDays,+ })+ : undefined;+const isBypassedSession = (ctx?: {sessionId?: string;sessionKey?: string;@@ -738,6 +821,169 @@ const contextEnginePlugin = {assistantPeerId: session.agentId,});+ const toTraceResult = (+ item: FindResultItem,+ resultType: RecallTraceResult["resultType"],+ ): RecallTraceResult => ({+ uri: item.uri,+ resourceType: inferRecallResourceType(item.uri),+ category: item.category,+ score: item.score,+ level: item.level,+ abstractPreview: previewText(item.abstract || item.overview, cfg.traceRecallPreviewChars),+ resultType,+ });++ const parseRecallTraceInput = (+ input: RecallTraceToolInput,+ ctx: { sessionId?: string; sessionKey?: string; ovSessionId?: string },+ ): RecallTraceQuery => ({+ turn: input.turn === "all" ? "all" : "latest",+ traceId: typeof input.traceId === "string" && input.traceId.trim() ? input.traceId.trim() : undefined,+ sessionId: typeof input.sessionId === "string" && input.sessionId.trim() ? input.sessionId.trim() : ctx.sessionId,+ sessionKey: typeof input.sessionKey === "string" && input.sessionKey.trim() ? input.sessionKey.trim() : undefined,+ ovSessionId: typeof input.ovSessionId === "string" && input.ovSessionId.trim() ? input.ovSessionId.trim() : ctx.ovSessionId,+ source: typeof input.source === "string" && input.source.trim() ? input.source as RecallTraceSource : undefined,+ resourceTypes: input.resourceTypes ? normalizeResourceTypes(input.resourceTypes) : undefined,+ since: typeof input.since === "number" ? input.since : undefined,+ until: typeof input.until === "number" ? input.until : undefined,+ limit: getPositiveInteger(input.limit, 20),+ });++ const shouldIncludeTraceContent = (input?: { includeContent?: boolean }): boolean =>+ input?.includeContent === true || cfg.traceRecallIncludeContentByDefault;++ const enrichTraceEntriesWithContent = async (+ result: { entries: RecallTraceEntry[]; lookupLayer: "memory" | "persistent"; warnings: string[] },+ includeContent: boolean,+ agentId?: string,+ ): Promise<{ entries: RecallTraceEntry[]; lookupLayer: "memory" | "persistent"; warnings: string[] }> => {+ if (!includeContent || result.entries.length === 0) {+ return result;+ }+ const client = await getClient();+ const warnings = [...result.warnings];+ const entries = await Promise.all(result.entries.map(async (entry) => {+ const selected = await Promise.all(entry.selected.map(async (item) => {+ try {+ const content = await client.read(item.uri, agentId);+ return {+ ...item,+ contentPreview: previewText(content, cfg.recallMaxContentChars),+ };+ } catch (err) {+ const readError = err instanceof Error ? err.message : String(err);+ warnings.push(`Failed to read recall trace content ${item.uri}: ${readError}`);+ return { ...item, readError };+ }+ }));+ return { ...entry, selected };+ }));+ return { ...result, entries, warnings };+ };++ const queryRecallTraces = async (+ input: RecallTraceToolInput,+ session: PluginSessionRouting,+ ): Promise<{ entries: RecallTraceEntry[]; lookupLayer: "memory" | "persistent"; warnings: string[] }> => {+ const base = traceRecorder+ ? await traceRecorder.queryWithFallback(parseRecallTraceInput(input, session))+ : { entries: [], lookupLayer: "memory" as const, warnings: ["traceRecall is disabled"] };+ return enrichTraceEntriesWithContent(base, shouldIncludeTraceContent(input), session.agentId);+ };++ const registerRecallTraceRoutes = (ctx?: unknown): boolean => {+ const routeAdapter = ctx as RecallTraceRouteAdapter | undefined;+ if (typeof routeAdapter?.registerRoute !== "function") {+ return false;+ }+ const toQueryObject = (request?: {+ query?: Record<string, unknown>;+ params?: Record<string, unknown>;+ url?: string;+ }) => {+ const query: Record<string, unknown> = { ...(request?.query ?? {}) };+ if (request?.url) {+ const parsed = new URL(request.url, "http://openclaw.local");+ for (const [key, value] of parsed.searchParams.entries()) {+ query[key] = value;+ }+ }+ return { ...query, ...(request?.params ?? {}) };+ };+ const toBoolean = (value: unknown): boolean | undefined => {+ if (typeof value === "boolean") return value;+ if (typeof value !== "string") return undefined;+ return ["1", "true", "yes"].includes(value.trim().toLowerCase());+ };+ const toNumber = (value: unknown): number | undefined => {+ if (typeof value === "number") return value;+ if (typeof value === "string" && value.trim()) {+ const parsed = Number(value);+ return Number.isFinite(parsed) ? parsed : undefined;+ }+ return undefined;+ };+ const handle = async (request?: {+ query?: Record<string, unknown>;+ params?: Record<string, unknown>;+ url?: string;+ }) => {+ const query = toQueryObject(request);+ const session = resolvePluginSessionRouting(query as SessionAgentLookup);+ const result = await queryRecallTraces({+ turn: query.turn === "all" ? "all" : "latest",+ traceId: typeof query.traceId === "string" ? query.traceId : undefined,+ sessionId: typeof query.sessionId === "string" ? query.sessionId : undefined,+ sessionKey: typeof query.sessionKey === "string" ? query.sessionKey : undefined,+ ovSessionId: typeof query.ovSessionId === "string" ? query.ovSessionId : undefined,+ source: typeof query.source === "string" ? query.source as RecallTraceSource : undefined,+ resourceTypes: typeof query.resourceTypes === "string" ? query.resourceTypes : undefined,+ since: toNumber(query.since),+ until: toNumber(query.until),+ includeContent: toBoolean(query.includeContent),+ limit: toNumber(query.limit),+ }, session);+ return { status: 200, body: { ok: true, ...result } };+ };+ routeAdapter.registerRoute({ method: "GET", path: "/api/openviking/recall-traces", handler: handle });+ routeAdapter.registerRoute({+ method: "GET",+ path: "/api/openviking/recall-traces/:traceId",+ handler: (request) => handle({+ ...request,+ query: {+ ...(request?.query ?? {}),+ traceId: typeof request?.params?.traceId === "string" ? request.params.traceId : undefined,+ },+ }),+ });+ return true;+ };++ const formatRecallTraceText = (result: { entries: RecallTraceEntry[]; lookupLayer: string; warnings: string[] }): string => {+ if (result.entries.length === 0) {+ return `No OpenViking recall traces found (lookupLayer=${result.lookupLayer}).`;+ }+ const blocks = result.entries.map((entry, index) => {+ const selected = entry.selected.slice(0, 8)+ .map((item) => ` - ${item.uri}${item.score !== undefined ? ` (${(clampScore(item.score) * 100).toFixed(0)}%)` : ""}`)+ .join("\n");+ return [+ `## Trace ${index + 1}: ${entry.source}`,+ `traceId: ${entry.traceId}`,+ `query: ${entry.trigger.query}`,+ `resourceTypes: ${entry.resourceTypes.join(", ")}`,+ `stats: candidates=${entry.stats.candidateCount}, selected=${entry.stats.selectedCount}, injected=${entry.stats.injectedCount}`,+ selected ? `selected:\n${selected}` : "selected: (none)",+ ].join("\n");+ });+ const warnings = result.warnings.length > 0+ ? `\n\nWarnings:\n${result.warnings.map((warning) => `- ${warning}`).join("\n")}`+ : "";+ return `${blocks.join("\n\n")}${warnings}`;+ };+const formatResourceImportText = (result: AddResourceResult): string => {const root = result.root_uri ? ` ${result.root_uri}` : "";const warnings = result.warnings?.length ? ` Warnings: ${result.warnings.join("; ")}` : "";@@ -919,6 +1165,7 @@ const contextEnginePlugin = {input: OVSearchInput,agentId?: string,peerId?: string,+ traceCtx?: PluginSessionRouting,) => {const query = input.query.trim();if (!query) {@@ -927,12 +1174,59 @@ const contextEnginePlugin = {const limit = Math.max(1, Math.floor(input.limit ?? 10));const client = await getClient();let result: FindResult;+ const searches: RecallTraceEntry["searches"] = [];if (input.uri) {+ const started = Date.now();result = await client.find(query, { targetUri: input.uri, limit, peerId }, agentId);+ const items = [+ ...(result.memories ?? []).map((item) => toTraceResult(item, "memory")),+ ...(result.resources ?? []).map((item) => toTraceResult(item, "resource")),+ ...(result.skills ?? []).map((item) => toTraceResult(item, "skill")),+ ].slice(0, cfg.traceRecallMaxResultsPerSearch);+ searches.push({+ resourceType: inferRecallResourceType(input.uri) ?? "resource",+ targetUriInput: input.uri,+ targetUriResolved: input.uri,+ limit,+ durationMs: Date.now() - started,+ total: result.total ?? items.length,+ results: items,+ });} else {+ const runSearch = async (targetUri: string): Promise<FindResult> => {+ const started = Date.now();+ try {+ const found = await client.find(query, { targetUri, limit, peerId }, agentId);+ const items = [+ ...(found.memories ?? []).map((item) => toTraceResult(item, "memory")),+ ...(found.resources ?? []).map((item) => toTraceResult(item, "resource")),+ ...(found.skills ?? []).map((item) => toTraceResult(item, "skill")),+ ].slice(0, cfg.traceRecallMaxResultsPerSearch);+ searches.push({+ resourceType: inferRecallResourceType(targetUri) ?? "resource",+ targetUriResolved: targetUri,+ limit,+ durationMs: Date.now() - started,+ total: found.total ?? items.length,+ results: items,+ });+ return found;+ } catch (err) {+ searches.push({+ resourceType: inferRecallResourceType(targetUri) ?? "resource",+ targetUriResolved: targetUri,+ limit,+ durationMs: Date.now() - started,+ total: 0,+ results: [],+ error: err instanceof Error ? err.message : String(err),+ });+ throw err;+ }+ };const [resourcesSettled, skillsSettled] = await Promise.allSettled([- client.find(query, { targetUri: "viking://resources", limit, peerId }, agentId),- client.find(query, { targetUri: "viking://user/skills", limit, peerId }, agentId),+ runSearch("viking://resources"),+ runSearch("viking://user/skills"),]);const successful: FindResult[] = [];if (resourcesSettled.status === "fulfilled") {@@ -958,6 +1252,54 @@ const contextEnginePlugin = {}result = mergeFindResults(successful);}+ const selected = [+ ...(result.memories ?? []).map((item) => ({+ uri: item.uri,+ resourceType: inferRecallResourceType(item.uri),+ category: item.category,+ score: item.score,+ abstractPreview: previewText(item.abstract || item.overview, cfg.traceRecallPreviewChars),+ displayed: true,+ })),+ ...(result.resources ?? []).map((item) => ({+ uri: item.uri,+ resourceType: inferRecallResourceType(item.uri),+ category: item.category,+ score: item.score,+ abstractPreview: previewText(item.abstract || item.overview, cfg.traceRecallPreviewChars),+ displayed: true,+ })),+ ...(result.skills ?? []).map((item) => ({+ uri: item.uri,+ resourceType: inferRecallResourceType(item.uri),+ category: item.category,+ score: item.score,+ abstractPreview: previewText(item.abstract || item.overview, cfg.traceRecallPreviewChars),+ displayed: true,+ })),+ ];+ await traceRecorder?.recordAndFlush({+ schemaVersion: "1.0",+ traceId: createTraceId("ov_search"),+ ts: Date.now(),+ sessionId: traceCtx?.sessionId,+ sessionKey: traceCtx?.sessionKey,+ ovSessionId: traceCtx?.ovSessionId,+ agentId,+ source: "ov_search",+ operationType: "semantic_find",+ resourceTypes: [...new Set(searches+ .map((search) => search.resourceType)+ .filter((resourceType): resourceType is RecallResourceType => resourceType !== "archive"))],+ trigger: boundTraceQuery(query, cfg.traceRecallQueryMaxChars),+ searches,+ selected,+ stats: {+ candidateCount: searches.reduce((sum, search) => sum + search.results.length, 0),+ selectedCount: selected.length,+ injectedCount: 0,+ },+ });return {content: [{ type: "text" as const, text: formatOVSearchText(query, input.uri, result) }],details: {@@ -1151,7 +1493,7 @@ const contextEnginePlugin = {query: String((params as { query?: unknown }).query ?? ""),uri: typeof params.uri === "string" ? params.uri : undefined,limit: typeof params.limit === "number" ? params.limit : undefined,- }, session.agentId, peerId);+ }, session.agentId, peerId, session);},}),{ name: "ov_search" },@@ -1288,7 +1630,7 @@ const contextEnginePlugin = {const session = resolvePluginSessionRouting(ctx);const input = parseOVSearchCommandArgs(ctx.args ?? "");const peerId = resolveToolSearchPeerId(ctx, session);- const result = await searchOpenViking(input, session.agentId, peerId);+ const result = await searchOpenViking(input, session.agentId, peerId, session);return { text: result.content[0]!.text, details: result.details };} catch (err) {return { text: `OpenViking search failed: ${err instanceof Error ? err.message : String(err)}` };@@ -1344,9 +1686,11 @@ const contextEnginePlugin = {);}- let result;+ let result: FindResult;+ let memoryRecallSearches: RecallTraceEntry["searches"] = [];if (targetUri) {// 如果指定了目标 URI,只检索该位置+ const started = Date.now();result = await recallClient.find(query,{@@ -1357,6 +1701,21 @@ const contextEnginePlugin = {},session.agentId,);+ const traceResults = [+ ...(result.memories ?? []).map((item) => toTraceResult(item, "memory")),+ ...(result.resources ?? []).map((item) => toTraceResult(item, "resource")),+ ...(result.skills ?? []).map((item) => toTraceResult(item, "skill")),+ ].slice(0, cfg.traceRecallMaxResultsPerSearch);+ memoryRecallSearches = [{+ resourceType: inferRecallResourceType(targetUri) ?? "resource",+ targetUriInput: targetUri,+ targetUriResolved: targetUri,+ limit: requestLimit,+ scoreThreshold,+ durationMs: Date.now() - started,+ total: result.total ?? traceResults.length,+ results: traceResults,+ }];} else {const searchPromises: Promise<FindResult>[] = [recallClient.find(@@ -1369,16 +1728,6 @@ const contextEnginePlugin = {},session.agentId,),- recallClient.find(- query,- {- targetUri: "viking://user/memories",- limit: requestLimit,- scoreThreshold: 0,- peerId,- },- session.agentId,- ),];if (cfg.recallResources) {searchPromises.push(@@ -1396,9 +1745,42 @@ const contextEnginePlugin = {}const settled = await Promise.allSettled(searchPromises);const allMemories: FindResultItem[] = [];- for (const s of settled) {+ const targetUris = [+ "viking://user/memories",+ ...(cfg.recallResources ? ["viking://resources"] : []),+ ];+ for (let index = 0; index < settled.length; index += 1) {+ const s = settled[index]!;+ const targetUriResolved = targetUris[index] ?? "viking://user/memories";if (s.status === "fulfilled") {allMemories.push(...(s.value.memories ?? []), ...(s.value.resources ?? []));+ const traceResults = [+ ...(s.value.memories ?? []).map((item) => toTraceResult(item, "memory")),+ ...(s.value.resources ?? []).map((item) => toTraceResult(item, "resource")),+ ...(s.value.skills ?? []).map((item) => toTraceResult(item, "skill")),+ ].slice(0, cfg.traceRecallMaxResultsPerSearch);+ memoryRecallSearches.push({+ resourceType: inferRecallResourceType(targetUriResolved) ?? "user",+ targetUriInput: targetUriResolved,+ targetUriResolved,+ limit: requestLimit,+ scoreThreshold,+ durationMs: 0,+ total: s.value.total ?? traceResults.length,+ results: traceResults,+ });+ } else {+ memoryRecallSearches.push({+ resourceType: inferRecallResourceType(targetUriResolved) ?? "user",+ targetUriInput: targetUriResolved,+ targetUriResolved,+ limit: requestLimit,+ scoreThreshold,+ durationMs: 0,+ total: 0,+ results: [],+ error: s.reason instanceof Error ? s.reason.message : String(s.reason),+ });}}const uniqueMemories = allMemories.filter((memory, index, self) =>@@ -1417,7 +1799,54 @@ const contextEnginePlugin = {scoreThreshold,});const memories = pickMemoriesForInjection(processed, limit, query);+ const candidateTraceResults = leafOnly+ .map((item) => toTraceResult(item, inferRecallResourceType(item.uri) === "resource" ? "resource" : "memory"))+ .slice(0, cfg.traceRecallMaxResultsPerSearch);+ const traceResourceTypes = [...new Set(+ (targetUri ? [inferRecallResourceType(targetUri)] : memoryRecallSearches.map((search) => search.resourceType))+ .filter((resourceType): resourceType is RecallResourceType => Boolean(resourceType) && resourceType !== "archive"),+ )];+ const recordMemoryRecallTrace = async (injectedUris: Set<string>) => {+ await traceRecorder?.recordAndFlush({+ schemaVersion: "1.0",+ traceId: createTraceId("memory_recall"),+ ts: Date.now(),+ sessionId: session.sessionId,+ sessionKey: session.sessionKey,+ ovSessionId: session.ovSessionId,+ agentId: session.agentId,+ source: "memory_recall",+ operationType: "semantic_find",+ resourceTypes: traceResourceTypes.length > 0 ? traceResourceTypes : ["user"],+ trigger: boundTraceQuery(query, cfg.traceRecallQueryMaxChars),+ searches: memoryRecallSearches.length > 0 ? memoryRecallSearches : [{+ resourceType: inferRecallResourceType(targetUri) ?? "user",+ targetUriInput: targetUri,+ targetUriResolved: targetUri ?? "viking://user/memories",+ limit: requestLimit,+ scoreThreshold,+ durationMs: 0,+ total: result.total ?? leafOnly.length,+ results: candidateTraceResults,+ }],+ selected: memories.map((item) => ({+ uri: item.uri,+ resourceType: inferRecallResourceType(item.uri),+ category: item.category,+ score: item.score,+ abstractPreview: previewText(item.abstract || item.overview, cfg.traceRecallPreviewChars),+ injected: injectedUris.has(item.uri),+ displayed: injectedUris.has(item.uri),+ })),+ stats: {+ candidateCount: leafOnly.length,+ selectedCount: memories.length,+ injectedCount: injectedUris.size,+ },+ });+ };if (memories.length === 0) {+ await recordMemoryRecallTrace(new Set());return {content: [{ type: "text", text: "No relevant OpenViking memories found." }],details: { count: 0, total: result.total ?? 0, scoreThreshold },@@ -1432,6 +1861,7 @@ const contextEnginePlugin = {},);if (memoryLines.length === 0) {+ await recordMemoryRecallTrace(new Set());return {content: [{@@ -1449,6 +1879,7 @@ const contextEnginePlugin = {},};}+ await recordMemoryRecallTrace(new Set(memories.slice(0, memoryLines.length).map((item) => item.uri)));return {content: [{@@ -1470,6 +1901,86 @@ const contextEnginePlugin = {{ name: "memory_recall" },);+ registerOpenVikingTool(+ (ctx: ToolContext) => ({+ name: "ov_recall_trace",+ label: "Recall Trace (OpenViking)",+ description: "Query OpenViking recall trace records captured by auto-recall and explicit recall/search tools.",+ parameters: Type.Object({+ turn: Type.Optional(Type.String({ description: "latest or all (default: latest)" })),+ traceId: Type.Optional(Type.String({ description: "Exact trace id" })),+ sessionId: Type.Optional(Type.String({ description: "OpenClaw session id" })),+ sessionKey: Type.Optional(Type.String({ description: "OpenClaw session key" })),+ ovSessionId: Type.Optional(Type.String({ description: "OpenViking session id" })),+ source: Type.Optional(Type.String({ description: "auto_recall, memory_recall, ov_search, or ov_archive_search" })),+ resourceTypes: Type.Optional(Type.Array(Type.String({ description: "resource, session, user, or agent" }))),+ since: Type.Optional(Type.Number({ description: "Unix timestamp lower bound in milliseconds" })),+ until: Type.Optional(Type.Number({ description: "Unix timestamp upper bound in milliseconds" })),+ includeContent: Type.Optional(Type.Boolean({ description: "Read selected/displayed URI content previews on demand" })),+ limit: Type.Optional(Type.Number({ description: "Maximum traces to return (default: 20)" })),+ }),+ async execute(_toolCallId: string, params: Record<string, unknown>) {+ if (isBypassedSession(ctx)) {+ return makeBypassedToolResult("ov_recall_trace");+ }+ const session = resolvePluginSessionRouting(ctx);+ const result = await queryRecallTraces(params as RecallTraceToolInput, session);+ return {+ content: [{ type: "text" as const, text: formatRecallTraceText(result) }],+ details: {+ action: "queried",+ count: result.entries.length,+ lookupLayer: result.lookupLayer,+ warnings: result.warnings,+ entries: result.entries,+ },+ };+ },+ }),+ { name: "ov_recall_trace" },+ );++ api.registerCommand?.({+ name: "ov-recall-trace",+ description: "Query OpenViking recall trace records.",+ acceptsArgs: true,+ handler: async (ctx: PluginCommandContext) => {+ try {+ if (isBypassedSession(ctx)) {+ const bypassed = makeBypassedToolResult("ov_recall_trace");+ return { text: bypassed.content[0]!.text, details: bypassed.details };+ }+ const session = resolvePluginSessionRouting(ctx);+ const flags = parseFlagArgs(ctx.args ?? "").flags;+ const input: RecallTraceToolInput = {+ turn: getStringFlag(flags, "turn") as "latest" | "all" | undefined,+ traceId: getStringFlag(flags, "trace-id"),+ sessionId: getStringFlag(flags, "session-id"),+ sessionKey: getStringFlag(flags, "session-key"),+ ovSessionId: getStringFlag(flags, "ov-session-id"),+ source: getStringFlag(flags, "source") as RecallTraceSource | undefined,+ resourceTypes: getStringFlag(flags, "resource-types"),+ since: getNumberFlag(flags, "since"),+ until: getNumberFlag(flags, "until"),+ includeContent: getBoolFlag(flags, "include-content"),+ limit: getNumberFlag(flags, "limit"),+ };+ const result = await queryRecallTraces(input, session);+ return {+ text: formatRecallTraceText(result),+ details: {+ count: result.entries.length,+ lookupLayer: result.lookupLayer,+ warnings: result.warnings,+ entries: result.entries,+ },+ };+ } catch (err) {+ return { text: `OpenViking recall trace query failed: ${err instanceof Error ? err.message : String(err)}` };+ }+ },+ });+registerOpenVikingTool((ctx: ToolContext) => ({name: "memory_store",@@ -1786,13 +2297,65 @@ const contextEnginePlugin = {try {const client = await getClient();const agentId = resolveAgentId(ctx.sessionId, ctx.sessionKey);+ const started = Date.now();const result = await client.grepSessionArchives(ovSessionId, escapedQuery, {archiveId,caseInsensitive: true,agentId,});+ const traceResults: RecallTraceResult[] = (result.matches ?? [])+ .slice(0, cfg.traceRecallMaxResultsPerSearch)+ .map((match) => ({+ uri: match.uri,+ resourceType: "archive",+ abstractPreview: previewText(match.content, cfg.traceRecallPreviewChars),+ resultType: "archive_match",+ }));+ const recordArchiveTrace = async (displayed: Array<{ uri: string; line: number; content: string }>) => {+ await traceRecorder?.recordAndFlush({+ schemaVersion: "1.0",+ traceId: createTraceId("ov_archive_search"),+ ts: Date.now(),+ sessionId: ctx.sessionId,+ sessionKey: ctx.sessionKey,+ ovSessionId,+ agentId,+ source: "ov_archive_search",+ operationType: "archive_grep",+ resourceTypes: ["session"],+ trigger: {+ ...boundTraceQuery(query, cfg.traceRecallQueryMaxChars),+ derivedKeywords: [query],+ },+ searches: [{+ resourceType: "archive",+ targetUriResolved: archiveId+ ? `${userSessionUri(ovSessionId)}/history/${archiveId}`+ : `${userSessionUri(ovSessionId)}/history`,+ limit: cfg.traceRecallMaxResultsPerSearch,+ durationMs: Date.now() - started,+ total: result.matches?.length ?? result.count ?? 0,+ results: traceResults,+ archiveId,+ caseInsensitive: true,+ }],+ selected: displayed.map((match) => ({+ uri: match.uri,+ resourceType: "archive",+ line: match.line,+ abstractPreview: previewText(match.content, cfg.traceRecallPreviewChars),+ displayed: true,+ })),+ stats: {+ candidateCount: result.matches?.length ?? result.count ?? 0,+ selectedCount: displayed.length,+ injectedCount: 0,+ },+ });+ };if (!result.matches || result.matches.length === 0) {+ await recordArchiveTrace([]);return {content: [{type: "text",@@ -1807,6 +2370,7 @@ const contextEnginePlugin = {const MAX_MATCHES = 12;const MAX_LINE_LEN = 1500;const shown = result.matches.slice(0, MAX_MATCHES);+ await recordArchiveTrace(shown);const blocks = shown.map((m, i) => {const archiveTag = m.uri.match(/archive_\d+/)?.[0] ?? "unknown";const truncated = m.content.length > MAX_LINE_LEN@@ -2270,6 +2834,7 @@ const contextEnginePlugin = {getClient,resolveAgentId,rememberSessionAgentId,+ traceRecorder,});return contextEngineRef;});@@ -2286,11 +2851,17 @@ const contextEnginePlugin = {api.registerService({id: "openviking",- start: async () => {+ start: async (ctx?: unknown) => {+ const routeRegistered = registerRecallTraceRoutes(ctx);await (await getClient()).healthCheck().catch(() => {});api.logger.info(`openviking: initialized (url: ${cfg.baseUrl}, targetUri: ${cfg.targetUri}, search: hybrid endpoint)`,);+ if (routeRegistered) {+ api.logger.info("openviking: registered recall trace Gateway routes");+ } else {+ api.logger.warn?.("openviking: recall trace Gateway route adapter unavailable; use ov_recall_trace tool or /ov-recall-trace command");+ }},stop: () => {api.logger.info("openviking: stopped");diff --git a/examples/openclaw-plugin/openclaw.plugin.json b/examples/openclaw-plugin/openclaw.plugin.jsonindex d57d670e1..8792a5d4e 100644--- a/examples/openclaw-plugin/openclaw.plugin.json+++ b/examples/openclaw-plugin/openclaw.plugin.json@@ -18,6 +18,7 @@"ov_multi_read","ov_list","memory_recall",+ "ov_recall_trace","memory_store","memory_forget","ov_archive_search",@@ -237,7 +238,7 @@"enabledTools": {"label": "Enabled Tools","placeholder": "default",- "help": "Agent-visible tool allowlist. Accepts tool names or groups: default, all, memory, resource_query, import, archive, tool_result. add_resource also requires enableAddResourceTool=true.",+ "help": "Agent-visible tool allowlist. Accepts tool names or groups: default, all, memory, resource_query, import, recall_trace, archive, tool_result. add_resource also requires enableAddResourceTool=true.","advanced": true},"disabledTools": {diff --git a/examples/openclaw-plugin/tests/ut/build-memory-lines.test.ts b/examples/openclaw-plugin/tests/ut/build-memory-lines.test.tsindex 6d077d12f..34c45e7df 100644--- a/examples/openclaw-plugin/tests/ut/build-memory-lines.test.ts+++ b/examples/openclaw-plugin/tests/ut/build-memory-lines.test.ts@@ -5,7 +5,10 @@ import {buildMemoryLines,buildMemoryLinesWithBudget,} from "../../index.js";+import { buildLongTermMemoryRecallContext } from "../../auto-recall.js";import type { FindResultItem } from "../../client.js";+import { memoryOpenVikingConfigSchema } from "../../config.js";+import { RecallTraceMemoryStore } from "../../recall-trace.js";function makeMemory(overrides?: Partial<FindResultItem>): FindResultItem {return {@@ -255,3 +258,123 @@ describe("buildMemoryLinesWithBudget", () => {expect(estimatedTokens).toBe(0);});});++describe("buildLongTermMemoryRecallContext trace", () => {+ function makeCfg(overrides: Record<string, unknown> = {}) {+ return memoryOpenVikingConfigSchema.parse({+ mode: "remote",+ baseUrl: "http://127.0.0.1:1933",+ autoRecall: true,+ recallPreferAbstract: true,+ ...overrides,+ });+ }++ it("records auto-recall trace without changing the generated section", async () => {+ const cfg = makeCfg();+ const memory = makeMemory({+ uri: "viking://user/memories/rust-pref",+ category: "preferences",+ abstract: "User prefers Rust for backend tasks.",+ score: 0.91,+ });+ const makeClient = () => ({+ healthCheck: vi.fn().mockResolvedValue(undefined),+ find: vi.fn().mockResolvedValue({ memories: [memory], total: 1 }),+ read: vi.fn().mockResolvedValue("unused"),+ });+ const logger = { info: vi.fn(), warn: vi.fn() };++ const withoutTrace = await buildLongTermMemoryRecallContext({+ cfg,+ client: makeClient() as any,+ agentId: "agent-1",+ queryText: "what backend language should we use?",+ logger,+ });+ const traces = new RecallTraceMemoryStore(10);+ const withTrace = await buildLongTermMemoryRecallContext({+ cfg,+ client: makeClient() as any,+ agentId: "agent-1",+ queryText: "what backend language should we use?",+ logger,+ traceRecorder: traces,+ sessionId: "session-1",+ ovSessionId: "ov-1",+ queryTruncated: false,+ });++ expect(withTrace.section).toBe(withoutTrace.section);+ const recorded = traces.query({ turn: "latest", sessionId: "session-1", limit: 10 }).entries[0]!;+ expect(recorded.source).toBe("auto_recall");+ expect(recorded.operationType).toBe("semantic_find");+ expect(recorded.resourceTypes).toEqual(["user"]);+ expect(recorded.trigger).toMatchObject({+ query: "what backend language should we use?",+ queryTruncated: false,+ });+ expect(recorded.searches).toHaveLength(1);+ expect(recorded.searches[0]).toMatchObject({+ resourceType: "user",+ targetUriInput: "viking://user/memories",+ total: 1,+ });+ expect(recorded.searches[0]!.results[0]).toMatchObject({+ uri: "viking://user/memories/rust-pref",+ resourceType: "user",+ resultType: "memory",+ });+ expect(recorded.selected[0]).toMatchObject({+ uri: "viking://user/memories/rust-pref",+ injected: true,+ });+ expect(recorded.stats.injectedCount).toBe(1);+ });++ it("records search errors while still injecting successful recall hits", async () => {+ const cfg = makeCfg({ recallResources: true });+ const client = {+ healthCheck: vi.fn().mockResolvedValue(undefined),+ find: vi.fn()+ .mockRejectedValueOnce(new Error("user search failed"))+ .mockResolvedValueOnce({+ resources: [makeMemory({+ uri: "viking://resources/backend-pref",+ abstract: "Use TypeScript for this service.",+ score: 0.88,+ })],+ total: 1,+ }),+ read: vi.fn().mockResolvedValue("unused"),+ };+ const logger = { info: vi.fn(), warn: vi.fn() };+ const traces = new RecallTraceMemoryStore(10);++ const result = await buildLongTermMemoryRecallContext({+ cfg,+ client: client as any,+ agentId: "agent-1",+ queryText: "which language should this service use?",+ logger,+ traceRecorder: traces,+ sessionId: "session-err",+ });++ expect(result.section).toContain("Use TypeScript for this service.");+ const recorded = traces.query({ turn: "latest", sessionId: "session-err", limit: 10 }).entries[0]!;+ expect(recorded.searches).toHaveLength(2);+ expect(recorded.searches[0]).toMatchObject({+ resourceType: "user",+ targetUriInput: "viking://user/memories",+ error: "Error: user search failed",+ });+ expect(recorded.searches[1]).toMatchObject({+ resourceType: "resource",+ targetUriInput: "viking://resources",+ total: 1,+ });+ expect(recorded.selected[0]).toMatchObject({ injected: true });+ expect(logger.warn).toHaveBeenCalledWith(expect.stringContaining("auto-recall search failed"));+ });+});diff --git a/examples/openclaw-plugin/tests/ut/context-engine-assemble.test.ts b/examples/openclaw-plugin/tests/ut/context-engine-assemble.test.tsindex ab32733af..a2c4a50bb 100644--- a/examples/openclaw-plugin/tests/ut/context-engine-assemble.test.ts+++ b/examples/openclaw-plugin/tests/ut/context-engine-assemble.test.ts@@ -3,6 +3,7 @@ import { describe, expect, it, vi } from "vitest";import type { OpenVikingClient } from "../../client.js";import { memoryOpenVikingConfigSchema } from "../../config.js";import { createMemoryOpenVikingContextEngine } from "../../context-engine.js";+import { RecallTraceMemoryStore } from "../../recall-trace.js";import { estimateAgentMessagesTokens, estimateTextTokens } from "../../token-estimator.js";const cfg = memoryOpenVikingConfigSchema.parse({@@ -43,6 +44,7 @@ function makeEngine(contextResult: unknown,opts?: {cfgOverrides?: Record<string, unknown>;+ traceRecorder?: RecallTraceMemoryStore;},) {const logger = makeLogger();@@ -69,6 +71,7 @@ function makeEngine(logger,getClient,resolveAgentId,+ traceRecorder: opts?.traceRecorder,});return {@@ -152,6 +155,50 @@ describe("context-engine assemble()", () => {expect(result.systemPromptAddition).toBeUndefined();});+ it("passes session metadata into auto-recall trace recording during transformContext", async () => {+ const traces = new RecallTraceMemoryStore(10);+ const { engine, client } = makeEngine(+ {+ latest_archive_overview: "unused",+ pre_archive_abstracts: [],+ messages: [],+ estimatedTokens: 0,+ stats: makeStats(),+ },+ {+ traceRecorder: traces,+ cfgOverrides: {+ autoRecall: true,+ recallPreferAbstract: true,+ },+ },+ );+ client.find.mockResolvedValueOnce({+ memories: [+ {+ uri: "viking://user/default/memories/typescript-pref",+ level: 2,+ category: "preferences",+ abstract: "Use TypeScript for gateway plugins.",+ score: 0.9,+ },+ ],+ total: 1,+ });++ await engine.assemble({+ sessionId: "session-transform-trace",+ messages: [{ role: "user", content: "which language should the gateway plugin use?" }],+ });++ const recorded = traces.query({ turn: "latest", sessionId: "session-transform-trace", limit: 10 }).entries[0]!;+ expect(recorded.sessionId).toBe("session-transform-trace");+ expect(recorded.ovSessionId).toBe("session-transform-trace");+ expect(recorded.agentId).toBe("agent:session-transform-trace");+ expect(recorded.trigger.query).toBe("which language should the gateway plugin use?");+ expect(recorded.resourceTypes).toEqual(["user"]);+ });+it("passes sender peer_id to transformContext auto-recall when peer_role is person", async () => {vi.stubGlobal("fetch",diff --git a/examples/openclaw-plugin/tests/ut/tools.test.ts b/examples/openclaw-plugin/tests/ut/tools.test.tsindex b5feba420..acf102aa6 100644--- a/examples/openclaw-plugin/tests/ut/tools.test.ts+++ b/examples/openclaw-plugin/tests/ut/tools.test.ts@@ -239,7 +239,7 @@ describe("Tool: memory_recall (registration)", () => {const findCalls = fetchMock.mock.calls.filter(([calledUrl]) =>String(calledUrl).includes("/api/v1/search/find"));- expect(findCalls).toHaveLength(2);+ expect(findCalls).toHaveLength(1);for (const [, init] of findCalls) {const body = JSON.parse(String((init as RequestInit).body));expect(body.limit).toBe(20);@@ -276,7 +276,7 @@ describe("Tool: memory_recall (registration)", () => {const findBodies = fetchMock.mock.calls.filter(([calledUrl]) => String(calledUrl).includes("/api/v1/search/find")).map((call) => JSON.parse(String((call[1] as RequestInit).body)));- expect(findBodies).toHaveLength(2);+ expect(findBodies).toHaveLength(1);for (const body of findBodies) {expect(body.peer_id).toBe("wx_user-01_abc");}@@ -951,6 +951,43 @@ describe("Tool: add_resource, add_skill, and ov_search (registration)", () => {expect(props).toHaveProperty("limit");});+ it("registers ov_recall_trace tool and command", () => {+ const { tools, commands, api } = setupPlugin(undefined, { traceRecall: true });+ contextEnginePlugin.register(api as any);++ const tool = tools.get("ov_recall_trace");+ expect(tool).toBeDefined();+ expect(tool!.description).toContain("recall trace");+ const props = (tool!.parameters as any).properties;+ expect(props).toHaveProperty("traceId");+ expect(props).toHaveProperty("source");+ expect(props).toHaveProperty("resourceTypes");+ expect(props).toHaveProperty("includeContent");+ expect(props).toHaveProperty("limit");+ expect(commands.get("ov-recall-trace")).toMatchObject({+ acceptsArgs: true,+ description: "Query OpenViking recall trace records.",+ });+ });++ it("registers recall trace gateway routes when a route adapter is available", async () => {+ const { api } = setupPlugin(undefined, { traceRecall: true });+ contextEnginePlugin.register(api as any);+ const service = (api.registerService as any).mock.calls[0][0];+ const registerRoute = vi.fn();++ await service.start({ registerRoute });++ expect(registerRoute).toHaveBeenCalledWith(expect.objectContaining({+ method: "GET",+ path: "/api/openviking/recall-traces",+ }));+ expect(registerRoute).toHaveBeenCalledWith(expect.objectContaining({+ method: "GET",+ path: "/api/openviking/recall-traces/:traceId",+ }));+ });+it("applies enabledTools and disabledTools to runtime tool registration", () => {const { tools, api } = setupPlugin(undefined, {enabledTools: ["resource_query", "memory"],@@ -1078,6 +1115,272 @@ describe("Tool: ov_search (behavioral)", () => {expect(findBodies.some((body) => String(body.target_uri).startsWith("viking://user/") && String(body.target_uri).endsWith("/skills"))).toBe(true);});+ it("records ov_search recall traces when traceRecall is enabled", async () => {+ const fetchMock = vi.fn(async (url: string, init?: RequestInit) => {+ if (url.endsWith("/api/v1/system/status")) {+ return okResponse({ user: "default" });+ }+ if (url.includes("/api/v1/fs/ls")) {+ return okResponse([]);+ }+ if (url.endsWith("/api/v1/search/find")) {+ const body = JSON.parse(String(init?.body ?? "{}"));+ return okResponse({+ memories: [],+ resources: [+ {+ context_type: "resource",+ uri: body.target_uri === "viking://resources"+ ? "viking://resources/trace-design.md"+ : "viking://user/skills/trace-skill",+ level: 2,+ score: 0.88,+ category: "",+ match_reason: "",+ relations: [],+ abstract: "Trace design note",+ overview: null,+ },+ ],+ skills: [],+ total: 1,+ });+ }+ return okResponse({});+ });+ vi.stubGlobal("fetch", fetchMock);++ const { tools, api } = setupPlugin(undefined, { traceRecall: true });+ contextEnginePlugin.register(api as any);+ await tools.get("ov_search")!.execute("tc-search", { query: "trace design" });++ const result = await tools.get("ov_recall_trace")!.execute("tc-trace", {+ source: "ov_search",+ limit: 10,+ }) as ToolResult;++ expect(result.content[0]!.text).toContain("ov_search");+ expect(result.content[0]!.text).toContain("trace design");+ expect(result.details.count).toBe(1);+ const entry = (result.details.entries as any[])[0];+ expect(entry.source).toBe("ov_search");+ expect(entry.searches.length).toBeGreaterThan(0);+ expect(entry.selected[0].uri).toContain("trace");+ });++ it("includes selected trace content only when includeContent is requested", async () => {+ const fetchMock = vi.fn(async (url: string) => {+ const requestUrl = new URL(url);+ if (requestUrl.pathname === "/api/v1/search/find") {+ return okResponse({+ memories: [],+ resources: [makeMemory({+ uri: "viking://resources/project/spec.md",+ abstract: "Recall trace design spec",+ score: 0.88,+ })],+ skills: [],+ total: 1,+ });+ }+ if (requestUrl.pathname === "/api/v1/content/read") {+ expect(requestUrl.searchParams.get("uri")).toBe("viking://resources/project/spec.md");+ return okResponse("Full trace content with operational details");+ }+ return okResponse({});+ });+ vi.stubGlobal("fetch", fetchMock);++ const { tools, factoryTools, commands, api } = setupPlugin(undefined, { traceRecall: true });+ contextEnginePlugin.register(api as any);+ await tools.get("ov_search")!.execute("tc-search", { query: "trace design", uri: "viking://resources" });++ const traceTool = factoryTools.get("ov_recall_trace")!({ sessionId: "test-session" });+ const result = await traceTool.execute("tc-trace", { source: "ov_search", includeContent: true }) as ToolResult;+ const entry = (result.details.entries as any[])[0];+ expect(entry.selected[0].contentPreview).toContain("Full trace content");++ await commands.get("ov-recall-trace")!.handler({+ args: "--source ov_search --include-content",+ commandBody: "",+ sessionId: "test-session",+ });+ expect(fetchMock.mock.calls.filter(([calledUrl]) => String(calledUrl).includes("/api/v1/content/read")).length).toBeGreaterThanOrEqual(2);+ });++ it("queries recorded traces from memory without calling OpenViking find again", async () => {+ const fetchMock = vi.fn(async (url: string) => {+ const requestUrl = new URL(url);+ if (requestUrl.pathname === "/api/v1/search/find") {+ return okResponse({+ memories: [],+ resources: [makeMemory({+ uri: "viking://resources/project/spec.md",+ abstract: "Recall trace design spec",+ score: 0.88,+ })],+ skills: [],+ total: 1,+ });+ }+ return okResponse({});+ });+ vi.stubGlobal("fetch", fetchMock);++ const { tools, factoryTools, api } = setupPlugin(undefined, { traceRecall: true });+ contextEnginePlugin.register(api as any);+ await tools.get("ov_search")!.execute("tc-search", {+ query: "trace design",+ uri: "viking://resources",+ limit: 3,+ });++ fetchMock.mockClear();+ const traceTool = factoryTools.get("ov_recall_trace")!({ sessionId: "test-session" });+ const result = await traceTool.execute("tc-trace", {+ source: "ov_search",+ limit: 10,+ }) as ToolResult;++ expect(result.content[0]!.text).toContain("ov_search");+ expect(result.content[0]!.text).toContain("trace design");+ expect(result.content[0]!.text).toContain("viking://resources/project/spec.md");+ expect(result.details.count).toBe(1);+ expect(fetchMock.mock.calls.some(([calledUrl]) => String(calledUrl).includes("/api/v1/search/find"))).toBe(false);+ });++ it("bounds stored trace query text by traceRecallQueryMaxChars", async () => {+ const fetchMock = vi.fn(async (url: string) => {+ const requestUrl = new URL(url);+ if (requestUrl.pathname === "/api/v1/search/find") {+ return okResponse({ memories: [], resources: [], skills: [], total: 0 });+ }+ return okResponse({});+ });+ vi.stubGlobal("fetch", fetchMock);++ const { tools, factoryTools, api } = setupPlugin(undefined, {+ traceRecall: true,+ traceRecallQueryMaxChars: 200,+ });+ contextEnginePlugin.register(api as any);+ await tools.get("ov_search")!.execute("tc-search-long-query", {+ query: "q".repeat(500),+ uri: "viking://resources",+ });++ const trace = factoryTools.get("ov_recall_trace")!({ sessionId: "test-session" });+ const result = await trace.execute("tc-trace", { source: "ov_search", limit: 10 }) as ToolResult;+ const entry = (result.details.entries as any[])[0];++ expect(entry.trigger.query).toHaveLength(200);+ expect(entry.trigger.queryTruncated).toBe(true);+ });++ it("records explicit memory_recall traces without duplicate default searches", async () => {+ const fetchMock = vi.fn(async (url: string, init?: RequestInit) => {+ const requestUrl = new URL(url);+ if (requestUrl.pathname === "/api/v1/system/status") {+ return okResponse({ user: "default" });+ }+ if (requestUrl.pathname === "/api/v1/search/find") {+ const body = JSON.parse(String(init?.body ?? "{}"));+ return okResponse({+ memories: [makeMemory({+ uri: `${body.target_uri}/backend-pref`,+ abstract: "Backend preference",+ score: 0.91,+ })],+ resources: [],+ skills: [],+ total: 1,+ });+ }+ if (requestUrl.pathname === "/api/v1/content/read") {+ return okResponse("Full backend memory content");+ }+ return okResponse({});+ });+ vi.stubGlobal("fetch", fetchMock);++ const { factoryTools, api } = setupPlugin(undefined, { traceRecall: true });+ contextEnginePlugin.register(api as any);+ const recall = factoryTools.get("memory_recall")!({ sessionId: "test-session", agentId: "main" });+ await recall.execute("tc-recall", { query: "backend preference", limit: 1, scoreThreshold: 0.2 });++ const findBodies = fetchMock.mock.calls+ .filter(([calledUrl]) => String(calledUrl).includes("/api/v1/search/find"))+ .map(([, fetchInit]) => JSON.parse(String((fetchInit as RequestInit).body)));+ expect(findBodies).toHaveLength(1);+ expect(findBodies[0]!.target_uri).toBe("viking://user/default/memories");++ const trace = factoryTools.get("ov_recall_trace")!({ sessionId: "test-session" });+ const result = await trace.execute("tc-trace", { source: "memory_recall", limit: 10 }) as ToolResult;+ expect(result.content[0]!.text).toContain("memory_recall");+ expect(result.content[0]!.text).toContain("backend preference");++ const entry = (result.details.entries as any[])[0];+ expect(entry.resourceTypes).toEqual(["user"]);+ expect(entry.searches).toHaveLength(1);+ expect(entry.searches[0]).toMatchObject({+ resourceType: "user",+ targetUriResolved: "viking://user/memories",+ total: 1,+ });+ expect(entry.selected).toEqual(expect.arrayContaining([+ expect.objectContaining({+ uri: "viking://user/default/memories/backend-pref",+ injected: true,+ }),+ ]));+ });++ it("records archive search traces with displayed archive matches", async () => {+ const fetchMock = vi.fn(async (url: string) => {+ const requestUrl = new URL(url);+ if (requestUrl.pathname === "/api/v1/search/grep") {+ return okResponse({+ matches: [{+ line: 12,+ uri: "viking://user/sessions/test-session/history/archive_001#L12",+ content: "discussion about recall traces",+ }],+ count: 1,+ });+ }+ return okResponse({});+ });+ vi.stubGlobal("fetch", fetchMock);++ const { factoryTools, api } = setupPlugin(undefined, { traceRecall: true });+ contextEnginePlugin.register(api as any);+ const archiveSearch = factoryTools.get("ov_archive_search")!({ sessionId: "test-session", agentId: "main" });+ await archiveSearch.execute("tc-archive", { query: "recall traces" });++ const trace = factoryTools.get("ov_recall_trace")!({ sessionId: "test-session" });+ const result = await trace.execute("tc-trace", { source: "ov_archive_search", limit: 10 }) as ToolResult;++ expect(result.content[0]!.text).toContain("ov_archive_search");+ expect(result.content[0]!.text).toContain("recall traces");+ expect(result.content[0]!.text).toContain("archive_001");+ const entry = (result.details.entries as any[])[0];+ expect(entry.operationType).toBe("archive_grep");+ expect(entry.trigger.derivedKeywords).toEqual(["recall traces"]);+ expect(entry.searches[0]).toMatchObject({+ targetUriResolved: "viking://user/sessions/test-session/history",+ total: 1,+ caseInsensitive: true,+ });+ expect(entry.searches[0].durationMs).toBeGreaterThanOrEqual(0);+ expect(entry.selected).toEqual(expect.arrayContaining([+ expect.objectContaining({+ uri: "viking://user/sessions/test-session/history/archive_001#L12",+ abstractPreview: "discussion about recall traces",+ displayed: true,+ }),+ ]));+ });+it("passes assistant peer_id to ov_search when peer_role is assistant", async () => {const fetchMock = vi.fn(async (url: string, init?: RequestInit) => {if (url.endsWith("/api/v1/system/status")) {@@ -1422,16 +1725,16 @@ describe("OpenViking ov_search command parsing", () => {});describe("Plugin registration", () => {- it("registers all 13 default tools", () => {+ it("registers all 14 default tools", () => {const { api } = setupPlugin();contextEnginePlugin.register(api as any);- expect(api.registerTool).toHaveBeenCalledTimes(13);+ expect(api.registerTool).toHaveBeenCalledTimes(14);});- it("registers all 14 tools when add_resource is explicitly enabled", () => {+ it("registers all 15 tools when add_resource is explicitly enabled", () => {const { api } = setupPlugin(undefined, { enableAddResourceTool: true });contextEnginePlugin.register(api as any);- expect(api.registerTool).toHaveBeenCalledTimes(14);+ expect(api.registerTool).toHaveBeenCalledTimes(15);});it("registers add and search commands", () => {@@ -1449,6 +1752,10 @@ describe("Plugin registration", () => {acceptsArgs: true,description: "Search OpenViking resources and skills.",});+ expect(commands.get("ov-recall-trace")).toMatchObject({+ acceptsArgs: true,+ description: "Query OpenViking recall trace records.",+ });});it("add and search commands return usage errors when args are missing", async () => {