Skip to content

Self-evolving Context Database for AI Agents. Unify Agent Memory, Knowledge RAG and Skills.

feat(openclaw): wire recall trace runtime (#2589)

Mingjian Qued497b05aee92
diff --git a/examples/openclaw-plugin/auto-recall.ts b/examples/openclaw-plugin/auto-recall.ts
index 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.ts
index 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.ts
index 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.ts
index 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): boolea
return 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.json
index 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.ts
index 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.ts
index 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.ts
index 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 () => {