Skip to content

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

feat(openclaw): add recall trace core (#2587)

Mingjian Quee2ca85d8ec29
diff --git a/examples/openclaw-plugin/config.ts b/examples/openclaw-plugin/config.ts
index c24642d6d..768634f87 100644
--- a/examples/openclaw-plugin/config.ts
+++ b/examples/openclaw-plugin/config.ts
@@ -1,3 +1,5 @@
+import { homedir } from "node:os";
+
import { getEnv } from "./runtime-utils.js";
export type MemoryOpenVikingConfig = {
@@ -45,6 +47,30 @@ export type MemoryOpenVikingConfig = {
emitStandardDiagnostics?: boolean;
/** When true, log tenant routing for semantic find and session writes (messages/commit) to the plugin logger. */
logFindRequests?: boolean;
+ /** Enable recall trace recording. Default false. */
+ traceRecall?: boolean;
+ /** Persist recall traces to local JSONL files. Default false. */
+ traceRecallPersist?: boolean;
+ /** Directory for JSONL recall trace files. */
+ traceRecallDir?: string;
+ /** Number of days to retain persisted trace files. */
+ traceRecallRetentionDays?: number;
+ /** Number of recent persisted days to preload on startup. */
+ traceRecallLoadRecentDays?: number;
+ /** Maximum in-memory recall trace entries. */
+ traceRecallMaxEntries?: number;
+ /** Maximum candidate results stored per search in trace. */
+ traceRecallMaxResultsPerSearch?: number;
+ /** Preview character limit for persisted trace summaries. */
+ traceRecallPreviewChars?: number;
+ /** Maximum query characters preserved in trace. */
+ traceRecallQueryMaxChars?: number;
+ /** Maximum days to scan when querying persisted traces without explicit time bounds. */
+ traceRecallQueryMaxDays?: number;
+ /** Whether trace queries include full content by default. */
+ traceRecallIncludeContentByDefault?: boolean;
+ /** Whether raw user text preview may be persisted. Default false. */
+ traceRecallIncludeRawUserPreview?: boolean;
/** Agent-visible add_resource tool is disabled by default; manual /add-resource remains available. */
enableAddResourceTool?: boolean;
/** Agent-visible tool allowlist. Supports exact tool names or groups such as "memory" and "resource_query". */
@@ -84,6 +110,14 @@ const DEFAULT_BYPASS_SESSION_PATTERNS: string[] = [];
const DEFAULT_EMIT_STANDARD_DIAGNOSTICS = false;
const DEFAULT_PEER_ROLE = "none" as const;
const DEFAULT_PEER_PREFIX = "";
+const DEFAULT_TRACE_RECALL_DIR = "~/.openclaw/openviking/recall-traces";
+const DEFAULT_TRACE_RECALL_RETENTION_DAYS = 14;
+const DEFAULT_TRACE_RECALL_LOAD_RECENT_DAYS = 2;
+const DEFAULT_TRACE_RECALL_MAX_ENTRIES = 1000;
+const DEFAULT_TRACE_RECALL_MAX_RESULTS_PER_SEARCH = 20;
+const DEFAULT_TRACE_RECALL_PREVIEW_CHARS = 240;
+const DEFAULT_TRACE_RECALL_QUERY_MAX_CHARS = 4000;
+const DEFAULT_TRACE_RECALL_QUERY_MAX_DAYS = 14;
export const OPENVIKING_ADD_RESOURCE_TOOL_NAME = "add_resource" as const;
export const OPENVIKING_DEFAULT_ENABLED_TOOL_NAMES = [
"add_skill",
@@ -158,6 +192,16 @@ function resolveEnvVars(value: string): string {
});
}
+function expandHomeDir(value: string): string {
+ if (value === "~") {
+ return homedir();
+ }
+ if (value.startsWith("~/")) {
+ return `${homedir()}${value.slice(1)}`;
+ }
+ return value;
+}
+
function toNumber(value: unknown, fallback: number): number {
if (typeof value === "number" && Number.isFinite(value)) {
return value;
@@ -187,6 +231,10 @@ function toStringArray(value: unknown, fallback: string[]): string[] {
return fallback;
}
+function toIntegerInRange(value: unknown, fallback: number, min: number, max: number): number {
+ return Math.max(min, Math.min(max, Math.floor(toNumber(value, fallback))));
+}
+
function toRecord(value: unknown): Record<string, unknown> {
return value && typeof value === "object" && !Array.isArray(value)
? value as Record<string, unknown>
@@ -315,6 +363,18 @@ export const memoryOpenVikingConfigSchema = {
"ingestReplyAssistIgnoreSessionPatterns",
"emitStandardDiagnostics",
"logFindRequests",
+ "traceRecall",
+ "traceRecallPersist",
+ "traceRecallDir",
+ "traceRecallRetentionDays",
+ "traceRecallLoadRecentDays",
+ "traceRecallMaxEntries",
+ "traceRecallMaxResultsPerSearch",
+ "traceRecallPreviewChars",
+ "traceRecallQueryMaxChars",
+ "traceRecallQueryMaxDays",
+ "traceRecallIncludeContentByDefault",
+ "traceRecallIncludeRawUserPreview",
"enableAddResourceTool",
"enabledTools",
"disabledTools",
@@ -430,6 +490,56 @@ export const memoryOpenVikingConfigSchema = {
cfg.logFindRequests === true ||
envFlag("OPENVIKING_LOG_ROUTING") ||
envFlag("OPENVIKING_DEBUG"),
+ traceRecall: cfg.traceRecall === true,
+ traceRecallPersist: cfg.traceRecallPersist === true,
+ traceRecallDir:
+ typeof cfg.traceRecallDir === "string" && cfg.traceRecallDir.trim()
+ ? expandHomeDir(cfg.traceRecallDir.trim())
+ : expandHomeDir(DEFAULT_TRACE_RECALL_DIR),
+ traceRecallRetentionDays: toIntegerInRange(
+ cfg.traceRecallRetentionDays,
+ DEFAULT_TRACE_RECALL_RETENTION_DAYS,
+ 1,
+ 3650,
+ ),
+ traceRecallLoadRecentDays: toIntegerInRange(
+ cfg.traceRecallLoadRecentDays,
+ DEFAULT_TRACE_RECALL_LOAD_RECENT_DAYS,
+ 0,
+ 3650,
+ ),
+ traceRecallMaxEntries: toIntegerInRange(
+ cfg.traceRecallMaxEntries,
+ DEFAULT_TRACE_RECALL_MAX_ENTRIES,
+ 1,
+ 1_000_000,
+ ),
+ traceRecallMaxResultsPerSearch: toIntegerInRange(
+ cfg.traceRecallMaxResultsPerSearch,
+ DEFAULT_TRACE_RECALL_MAX_RESULTS_PER_SEARCH,
+ 1,
+ 1_000,
+ ),
+ traceRecallPreviewChars: toIntegerInRange(
+ cfg.traceRecallPreviewChars,
+ DEFAULT_TRACE_RECALL_PREVIEW_CHARS,
+ 20,
+ 10_000,
+ ),
+ traceRecallQueryMaxChars: toIntegerInRange(
+ cfg.traceRecallQueryMaxChars,
+ DEFAULT_TRACE_RECALL_QUERY_MAX_CHARS,
+ 200,
+ 200_000,
+ ),
+ traceRecallQueryMaxDays: toIntegerInRange(
+ cfg.traceRecallQueryMaxDays,
+ DEFAULT_TRACE_RECALL_QUERY_MAX_DAYS,
+ 1,
+ 3650,
+ ),
+ traceRecallIncludeContentByDefault: cfg.traceRecallIncludeContentByDefault === true,
+ traceRecallIncludeRawUserPreview: cfg.traceRecallIncludeRawUserPreview === true,
enableAddResourceTool: cfg.enableAddResourceTool === true,
enabledTools,
disabledTools,
@@ -606,6 +716,24 @@ export const memoryOpenVikingConfigSchema = {
"Or set env OPENVIKING_LOG_ROUTING=1 or OPENVIKING_DEBUG=1 (no JSON edit).",
advanced: true,
},
+ traceRecall: {
+ label: "Trace Recall",
+ placeholder: "false",
+ help: "Enable best-effort recall trace recording for debugging recall and search decisions.",
+ advanced: true,
+ },
+ traceRecallPersist: {
+ label: "Persist Recall Trace",
+ placeholder: "false",
+ help: "Persist recall traces to local JSONL files. Disabled by default.",
+ advanced: true,
+ },
+ traceRecallDir: {
+ label: "Recall Trace Directory",
+ placeholder: DEFAULT_TRACE_RECALL_DIR,
+ help: "Directory for persisted recall trace JSONL files.",
+ advanced: true,
+ },
enableAddResourceTool: {
label: "Enable Add Resource Tool",
placeholder: "false",
diff --git a/examples/openclaw-plugin/openclaw.plugin.json b/examples/openclaw-plugin/openclaw.plugin.json
index 1600ea71c..d57d670e1 100644
--- a/examples/openclaw-plugin/openclaw.plugin.json
+++ b/examples/openclaw-plugin/openclaw.plugin.json
@@ -210,6 +210,24 @@
"help": "Log tenant routing: /search/find + session messages/commit (X-OpenViking-*; not apiKey). Or set env OPENVIKING_LOG_ROUTING=1 or OPENVIKING_DEBUG=1.",
"advanced": true
},
+ "traceRecall": {
+ "label": "Trace Recall",
+ "placeholder": "false",
+ "help": "Enable best-effort recall trace recording for debugging recall and search decisions.",
+ "advanced": true
+ },
+ "traceRecallPersist": {
+ "label": "Persist Recall Trace",
+ "placeholder": "false",
+ "help": "Persist recall traces to local JSONL files. Disabled by default.",
+ "advanced": true
+ },
+ "traceRecallDir": {
+ "label": "Recall Trace Directory",
+ "placeholder": "~/.openclaw/openviking/recall-traces",
+ "help": "Directory for persisted recall trace JSONL files.",
+ "advanced": true
+ },
"enableAddResourceTool": {
"label": "Enable Add Resource Tool",
"placeholder": "false",
@@ -346,6 +364,56 @@
"logFindRequests": {
"type": "boolean"
},
+ "traceRecall": {
+ "type": "boolean"
+ },
+ "traceRecallPersist": {
+ "type": "boolean"
+ },
+ "traceRecallDir": {
+ "type": "string"
+ },
+ "traceRecallRetentionDays": {
+ "type": "number",
+ "minimum": 1,
+ "maximum": 3650
+ },
+ "traceRecallLoadRecentDays": {
+ "type": "number",
+ "minimum": 0,
+ "maximum": 3650
+ },
+ "traceRecallMaxEntries": {
+ "type": "number",
+ "minimum": 1,
+ "maximum": 1000000
+ },
+ "traceRecallMaxResultsPerSearch": {
+ "type": "number",
+ "minimum": 1,
+ "maximum": 1000
+ },
+ "traceRecallPreviewChars": {
+ "type": "number",
+ "minimum": 20,
+ "maximum": 10000
+ },
+ "traceRecallQueryMaxChars": {
+ "type": "number",
+ "minimum": 200,
+ "maximum": 200000
+ },
+ "traceRecallQueryMaxDays": {
+ "type": "number",
+ "minimum": 1,
+ "maximum": 3650
+ },
+ "traceRecallIncludeContentByDefault": {
+ "type": "boolean"
+ },
+ "traceRecallIncludeRawUserPreview": {
+ "type": "boolean"
+ },
"enableAddResourceTool": {
"type": "boolean"
},
diff --git a/examples/openclaw-plugin/recall-trace.ts b/examples/openclaw-plugin/recall-trace.ts
new file mode 100644
index 000000000..2db822d44
--- /dev/null
+++ b/examples/openclaw-plugin/recall-trace.ts
@@ -0,0 +1,447 @@
+import { appendFile, mkdir, readFile, readdir, unlink } from "node:fs/promises";
+import { join } from "node:path";
+
+export type RecallResourceType = "resource" | "session" | "user" | "agent";
+
+export type RecallTraceSource = "auto_recall" | "memory_recall" | "ov_search" | "ov_archive_search";
+
+export type RecallTraceOperationType = "semantic_find" | "archive_grep";
+
+export type RecallTraceResult = {
+ uri: string;
+ resourceType?: RecallResourceType | "archive";
+ category?: string;
+ score?: number;
+ level?: number;
+ abstractPreview?: string;
+ resultType: "memory" | "resource" | "skill" | "archive_match";
+};
+
+export type RecallTraceEntry = {
+ schemaVersion: "1.0";
+ traceId: string;
+ ts: number;
+ sessionId?: string;
+ sessionKey?: string;
+ ovSessionId?: string;
+ agentId?: string;
+ source: RecallTraceSource;
+ operationType: RecallTraceOperationType;
+ resourceTypes: RecallResourceType[];
+ trigger: {
+ rawUserTextPreview?: string;
+ query: string;
+ derivedKeywords?: string[];
+ queryTruncated?: boolean;
+ };
+ searches: Array<{
+ resourceType: RecallResourceType | "archive";
+ targetUriInput?: string;
+ targetUriResolved?: string;
+ limit: number;
+ scoreThreshold?: number;
+ durationMs: number;
+ total: number;
+ results: RecallTraceResult[];
+ archiveId?: string;
+ caseInsensitive?: boolean;
+ error?: string;
+ }>;
+ selected: Array<{
+ uri: string;
+ resourceType?: RecallResourceType | "archive";
+ category?: string;
+ score?: number;
+ line?: number;
+ abstractPreview?: string;
+ contentPreview?: string;
+ readError?: string;
+ injected?: boolean;
+ displayed?: boolean;
+ skippedReason?: "score_threshold" | "dedupe" | "non_leaf" | "budget" | "not_top_k" | "search_error";
+ }>;
+ stats: {
+ candidateCount: number;
+ selectedCount: number;
+ injectedCount: number;
+ estimatedTokens?: number;
+ };
+};
+
+export type RecallTraceQuery = {
+ turn?: "latest" | "all";
+ traceId?: string;
+ sessionId?: string;
+ sessionKey?: string;
+ ovSessionId?: string;
+ source?: RecallTraceSource;
+ resourceTypes?: RecallResourceType[];
+ since?: number;
+ until?: number;
+ limit?: number;
+};
+
+export type RecallTraceQueryResult = {
+ entries: RecallTraceEntry[];
+ lookupLayer: "memory" | "persistent";
+ warnings: string[];
+};
+
+export type RecallTraceFlushResult = {
+ warnings: string[];
+};
+
+const ALLOWED_RESOURCE_TYPES: RecallResourceType[] = ["resource", "session", "user", "agent"];
+const DEFAULT_RESOURCE_TYPES: RecallResourceType[] = ["user", "agent"];
+
+function toResourceTypeEntries(value: unknown): string[] {
+ if (Array.isArray(value)) {
+ return value
+ .filter((entry): entry is string => typeof entry === "string")
+ .map((entry) => entry.trim())
+ .filter(Boolean);
+ }
+ if (typeof value === "string") {
+ return value
+ .split(/[,\n]/)
+ .map((entry) => entry.trim())
+ .filter(Boolean);
+ }
+ return [];
+}
+
+export function normalizeResourceTypes(value: unknown): RecallResourceType[] {
+ const entries = toResourceTypeEntries(value);
+ if (entries.length === 0) {
+ return [...DEFAULT_RESOURCE_TYPES];
+ }
+
+ const seen = new Set<RecallResourceType>();
+ const normalized: RecallResourceType[] = [];
+ const invalid: string[] = [];
+ for (const entry of entries) {
+ if ((ALLOWED_RESOURCE_TYPES as string[]).includes(entry)) {
+ const typed = entry as RecallResourceType;
+ if (!seen.has(typed)) {
+ seen.add(typed);
+ normalized.push(typed);
+ }
+ } else {
+ invalid.push(entry);
+ }
+ }
+
+ if (invalid.length > 0) {
+ throw new Error(`invalid resourceTypes: ${invalid.join(", ")}`);
+ }
+
+ return normalized.length > 0 ? normalized : [...DEFAULT_RESOURCE_TYPES];
+}
+
+export function resolveRecallSearchPlan(
+ resourceTypes: unknown,
+ ctx: { ovSessionId?: string; agentId?: string },
+): {
+ resourceTypes: RecallResourceType[];
+ searches: Array<{ resourceType: RecallResourceType; targetUri: string }>;
+ skipped: Array<{ resourceType: RecallResourceType; reason: "missing_session" }>;
+} {
+ const normalized = normalizeResourceTypes(resourceTypes);
+ const searches: Array<{ resourceType: RecallResourceType; targetUri: string }> = [];
+ const skipped: Array<{ resourceType: RecallResourceType; reason: "missing_session" }> = [];
+
+ for (const resourceType of normalized) {
+ if (resourceType === "resource") {
+ searches.push({ resourceType, targetUri: "viking://resources" });
+ } else if (resourceType === "session") {
+ if (ctx.ovSessionId) {
+ searches.push({ resourceType, targetUri: `viking://session/${ctx.ovSessionId}/history` });
+ } else {
+ skipped.push({ resourceType, reason: "missing_session" });
+ }
+ } else if (resourceType === "user") {
+ searches.push({ resourceType, targetUri: "viking://user/memories" });
+ } else if (resourceType === "agent") {
+ searches.push({ resourceType, targetUri: "viking://agent/memories" });
+ }
+ }
+
+ return { resourceTypes: normalized, searches, skipped };
+}
+
+export class RecallTraceMemoryStore {
+ private readonly maxEntries: number;
+ private readonly entries: RecallTraceEntry[] = [];
+
+ constructor(maxEntries: number) {
+ this.maxEntries = Math.max(1, Math.floor(maxEntries));
+ }
+
+ record(entry: RecallTraceEntry): void {
+ this.entries.push(entry);
+ while (this.entries.length > this.maxEntries) {
+ this.entries.shift();
+ }
+ }
+
+ query(query: RecallTraceQuery): RecallTraceQueryResult {
+ const limit = Math.max(1, Math.floor(query.limit ?? 20));
+ const turn = query.turn ?? "latest";
+ const resourceTypes = query.resourceTypes && query.resourceTypes.length > 0
+ ? new Set(query.resourceTypes)
+ : undefined;
+
+ const filtered = this.entries
+ .filter((entry) => {
+ if (query.traceId && entry.traceId !== query.traceId) return false;
+ if (query.source && entry.source !== query.source) return false;
+ if (query.sessionId && entry.sessionId !== query.sessionId) return false;
+ if (query.sessionKey && entry.sessionKey !== query.sessionKey) return false;
+ if (query.ovSessionId && entry.ovSessionId !== query.ovSessionId) return false;
+ if (typeof query.since === "number" && entry.ts < query.since) return false;
+ if (typeof query.until === "number" && entry.ts > query.until) return false;
+ if (resourceTypes && !entry.resourceTypes.some((resourceType) => resourceTypes.has(resourceType))) {
+ return false;
+ }
+ return true;
+ })
+ .sort((a, b) => b.ts - a.ts);
+
+ return { entries: filtered.slice(0, turn === "latest" ? 1 : limit), lookupLayer: "memory", warnings: [] };
+ }
+}
+
+function jsonlFileNameForTimestamp(ts: number): string {
+ return `${new Date(ts).toISOString().slice(0, 10)}.jsonl`;
+}
+
+function startOfUtcDay(ts: number): number {
+ const d = new Date(ts);
+ return Date.UTC(d.getUTCFullYear(), d.getUTCMonth(), d.getUTCDate());
+}
+
+function timestampFromJsonlFileName(name: string): number | undefined {
+ const match = /^(\d{4})-(\d{2})-(\d{2})\.jsonl$/.exec(name);
+ if (!match) {
+ return undefined;
+ }
+ const ts = Date.UTC(Number(match[1]), Number(match[2]) - 1, Number(match[3]));
+ return Number.isFinite(ts) ? ts : undefined;
+}
+
+function fileMayOverlapQueryWindow(name: string, since: number, until: number): boolean {
+ const dayStart = timestampFromJsonlFileName(name);
+ if (dayStart === undefined) {
+ return true;
+ }
+ const dayEnd = dayStart + 86_400_000 - 1;
+ return dayEnd >= since && dayStart <= until;
+}
+
+function isRecallTraceEntry(value: unknown): value is RecallTraceEntry {
+ if (!value || typeof value !== "object" || Array.isArray(value)) {
+ return false;
+ }
+ const candidate = value as Partial<RecallTraceEntry>;
+ return candidate.schemaVersion === "1.0" &&
+ typeof candidate.traceId === "string" &&
+ typeof candidate.ts === "number" &&
+ typeof candidate.source === "string" &&
+ typeof candidate.operationType === "string" &&
+ Array.isArray(candidate.resourceTypes) &&
+ !!candidate.trigger &&
+ typeof candidate.trigger.query === "string";
+}
+
+export class RecallTraceJsonlStore {
+ private readonly dir: string;
+ private readonly includeRawUserPreview: boolean;
+ private readonly retentionDays: number;
+ private readonly queryMaxDays: number;
+ private readonly pending: Promise<void>[] = [];
+ private readonly warnings: string[] = [];
+
+ constructor(options: { dir: string; includeRawUserPreview?: boolean; retentionDays?: number; queryMaxDays?: number }) {
+ this.dir = options.dir;
+ this.includeRawUserPreview = options.includeRawUserPreview === true;
+ this.retentionDays = Math.max(1, Math.floor(options.retentionDays ?? 14));
+ this.queryMaxDays = Math.max(1, Math.floor(options.queryMaxDays ?? 14));
+ }
+
+ private entryForPersistence(entry: RecallTraceEntry): RecallTraceEntry {
+ if (this.includeRawUserPreview || entry.trigger.rawUserTextPreview === undefined) {
+ return entry;
+ }
+ return {
+ ...entry,
+ trigger: {
+ ...entry.trigger,
+ rawUserTextPreview: undefined,
+ },
+ };
+ }
+
+ append(entry: RecallTraceEntry): Promise<void> {
+ const write = (async () => {
+ await mkdir(this.dir, { recursive: true });
+ await this.pruneExpiredFiles(entry.ts);
+ await appendFile(
+ join(this.dir, jsonlFileNameForTimestamp(entry.ts)),
+ `${JSON.stringify(this.entryForPersistence(entry))}\n`,
+ "utf8",
+ );
+ })().catch((err: unknown) => {
+ this.warnings.push(`Failed to append recall trace JSONL: ${err instanceof Error ? err.message : String(err)}`);
+ });
+
+ this.pending.push(write);
+ return write;
+ }
+
+ private async pruneExpiredFiles(nowTs: number): Promise<void> {
+ const cutoff = startOfUtcDay(nowTs - this.retentionDays * 86_400_000);
+ let files: string[];
+ try {
+ files = await readdir(this.dir);
+ } catch {
+ return;
+ }
+ await Promise.all(files
+ .filter((name) => name.endsWith(".jsonl"))
+ .filter((name) => {
+ const ts = timestampFromJsonlFileName(name);
+ return ts !== undefined && ts < cutoff;
+ })
+ .map(async (name) => {
+ try {
+ await unlink(join(this.dir, name));
+ } catch (err: unknown) {
+ this.warnings.push(`Failed to prune recall trace file ${name}: ${err instanceof Error ? err.message : String(err)}`);
+ }
+ }));
+ }
+
+ async flush(): Promise<RecallTraceFlushResult> {
+ const pending = this.pending.splice(0);
+ await Promise.all(pending);
+ return { warnings: [...this.warnings] };
+ }
+
+ async query(query: RecallTraceQuery): Promise<RecallTraceQueryResult> {
+ await this.flush();
+ const warnings = [...this.warnings];
+ const entries: RecallTraceEntry[] = [];
+
+ let files: string[];
+ try {
+ files = await readdir(this.dir);
+ } catch (err: unknown) {
+ const code = typeof err === "object" && err !== null && "code" in err ? String((err as { code?: unknown }).code) : "";
+ if (code === "ENOENT") {
+ return { entries: [], lookupLayer: "persistent", warnings };
+ }
+ return {
+ entries: [],
+ lookupLayer: "persistent",
+ warnings: [...warnings, `Failed to read recall trace directory: ${err instanceof Error ? err.message : String(err)}`],
+ };
+ }
+
+ const queryStart = typeof query.since === "number"
+ ? query.since
+ : Date.now() - this.queryMaxDays * 86_400_000;
+ const queryEnd = typeof query.until === "number" ? query.until : Date.now();
+ for (const file of files
+ .filter((name) => name.endsWith(".jsonl"))
+ .filter((name) => fileMayOverlapQueryWindow(name, queryStart, queryEnd))
+ .sort()) {
+ const path = join(this.dir, file);
+ let content: string;
+ try {
+ content = await readFile(path, "utf8");
+ } catch (err: unknown) {
+ warnings.push(`Failed to read recall trace file ${file}: ${err instanceof Error ? err.message : String(err)}`);
+ continue;
+ }
+
+ const lines = content.split("\n");
+ for (let index = 0; index < lines.length; index++) {
+ const line = lines[index]!.trim();
+ if (!line) {
+ continue;
+ }
+ try {
+ const parsed: unknown = JSON.parse(line);
+ if (isRecallTraceEntry(parsed)) {
+ entries.push(parsed);
+ } else {
+ warnings.push(`Skipping corrupted recall trace line ${file}:${index + 1}`);
+ }
+ } catch {
+ warnings.push(`Skipping corrupted recall trace line ${file}:${index + 1}`);
+ }
+ }
+ }
+
+ const memory = new RecallTraceMemoryStore(Math.max(1, entries.length));
+ for (const entry of entries) {
+ memory.record(entry);
+ }
+ const filtered = memory.query(query);
+ return { entries: filtered.entries, lookupLayer: "persistent", warnings };
+ }
+}
+
+export class RecallTraceRecorder {
+ private readonly memory: RecallTraceMemoryStore;
+ private readonly persistent?: RecallTraceJsonlStore;
+
+ constructor(options: {
+ memoryMaxEntries: number;
+ persist: boolean;
+ traceDir: string;
+ includeRawUserPreview?: boolean;
+ retentionDays?: number;
+ queryMaxDays?: number;
+ }) {
+ this.memory = new RecallTraceMemoryStore(options.memoryMaxEntries);
+ this.persistent = options.persist ? new RecallTraceJsonlStore({
+ dir: options.traceDir,
+ includeRawUserPreview: options.includeRawUserPreview,
+ retentionDays: options.retentionDays,
+ queryMaxDays: options.queryMaxDays,
+ }) : undefined;
+ }
+
+ record(entry: RecallTraceEntry): void {
+ this.memory.record(entry);
+ void this.persistent?.append(entry);
+ }
+
+ async recordAndFlush(entry: RecallTraceEntry): Promise<RecallTraceFlushResult> {
+ this.memory.record(entry);
+ await this.persistent?.append(entry);
+ return this.flush();
+ }
+
+ query(query: RecallTraceQuery): RecallTraceQueryResult {
+ return this.memory.query(query);
+ }
+
+ async queryWithFallback(query: RecallTraceQuery): Promise<RecallTraceQueryResult> {
+ const memoryResult = this.memory.query(query);
+ if (memoryResult.entries.length > 0 || !this.persistent) {
+ return memoryResult;
+ }
+ const persistentResult = await this.persistent.query(query);
+ return {
+ entries: persistentResult.entries,
+ lookupLayer: "persistent",
+ warnings: [...memoryResult.warnings, ...persistentResult.warnings],
+ };
+ }
+
+ async flush(): Promise<RecallTraceFlushResult> {
+ return this.persistent ? this.persistent.flush() : { warnings: [] };
+ }
+}
diff --git a/examples/openclaw-plugin/tests/ut/config.test.ts b/examples/openclaw-plugin/tests/ut/config.test.ts
index 7f68f803c..bb3e48265 100644
--- a/examples/openclaw-plugin/tests/ut/config.test.ts
+++ b/examples/openclaw-plugin/tests/ut/config.test.ts
@@ -27,6 +27,18 @@ describe("memoryOpenVikingConfigSchema.parse()", () => {
expect(cfg.peer_role).toBe("none");
expect(cfg.peer_prefix).toBe("");
expect(cfg.emitStandardDiagnostics).toBe(false);
+ expect(cfg.traceRecall).toBe(false);
+ expect(cfg.traceRecallPersist).toBe(false);
+ expect(cfg.traceRecallDir).toContain(".openclaw/openviking/recall-traces");
+ expect(cfg.traceRecallRetentionDays).toBe(14);
+ expect(cfg.traceRecallLoadRecentDays).toBe(2);
+ expect(cfg.traceRecallMaxEntries).toBe(1000);
+ expect(cfg.traceRecallMaxResultsPerSearch).toBe(20);
+ expect(cfg.traceRecallPreviewChars).toBe(240);
+ expect(cfg.traceRecallQueryMaxChars).toBe(4000);
+ expect(cfg.traceRecallQueryMaxDays).toBe(14);
+ expect(cfg.traceRecallIncludeContentByDefault).toBe(false);
+ expect(cfg.traceRecallIncludeRawUserPreview).toBe(false);
expect(cfg.enableAddResourceTool).toBe(false);
expect(cfg.enabledTools).toContain("ov_search");
expect(cfg.enabledTools).toContain("ov_read");
@@ -77,6 +89,36 @@ describe("memoryOpenVikingConfigSchema.parse()", () => {
).toThrow("unknown tool selectors");
});
+ it("parses and clamps recall trace settings", () => {
+ const cfg = memoryOpenVikingConfigSchema.parse({
+ traceRecall: true,
+ traceRecallPersist: true,
+ traceRecallDir: "~/custom-traces",
+ traceRecallRetentionDays: 0,
+ traceRecallLoadRecentDays: -1,
+ traceRecallMaxEntries: 2_000_000,
+ traceRecallMaxResultsPerSearch: 0,
+ traceRecallPreviewChars: 5,
+ traceRecallQueryMaxChars: 100,
+ traceRecallQueryMaxDays: 9999,
+ traceRecallIncludeContentByDefault: true,
+ traceRecallIncludeRawUserPreview: true,
+ });
+
+ expect(cfg.traceRecall).toBe(true);
+ expect(cfg.traceRecallPersist).toBe(true);
+ expect(cfg.traceRecallDir).toContain("custom-traces");
+ expect(cfg.traceRecallRetentionDays).toBe(1);
+ expect(cfg.traceRecallLoadRecentDays).toBe(0);
+ expect(cfg.traceRecallMaxEntries).toBe(1_000_000);
+ expect(cfg.traceRecallMaxResultsPerSearch).toBe(1);
+ expect(cfg.traceRecallPreviewChars).toBe(20);
+ expect(cfg.traceRecallQueryMaxChars).toBe(200);
+ expect(cfg.traceRecallQueryMaxDays).toBe(3650);
+ expect(cfg.traceRecallIncludeContentByDefault).toBe(true);
+ expect(cfg.traceRecallIncludeRawUserPreview).toBe(true);
+ });
+
it("defaults recallMaxInjectedChars to the 4000-character memory budget", () => {
const cfg = memoryOpenVikingConfigSchema.parse({});
expect(cfg.recallMaxInjectedChars).toBe(4000);
diff --git a/examples/openclaw-plugin/tests/ut/recall-trace.test.ts b/examples/openclaw-plugin/tests/ut/recall-trace.test.ts
new file mode 100644
index 000000000..a8e8e6b1f
--- /dev/null
+++ b/examples/openclaw-plugin/tests/ut/recall-trace.test.ts
@@ -0,0 +1,300 @@
+import { existsSync, mkdirSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { afterEach, describe, expect, it } from "vitest";
+
+import {
+ RecallTraceJsonlStore,
+ RecallTraceMemoryStore,
+ RecallTraceRecorder,
+ normalizeResourceTypes,
+ resolveRecallSearchPlan,
+ type RecallTraceEntry,
+} from "../../recall-trace.js";
+
+const tempDirs: string[] = [];
+
+function makeTempDir(): string {
+ const dir = join(tmpdir(), `openviking-recall-trace-${process.pid}-${Date.now()}-${tempDirs.length}`);
+ mkdirSync(dir, { recursive: true });
+ tempDirs.push(dir);
+ return dir;
+}
+
+afterEach(() => {
+ for (const dir of tempDirs.splice(0)) {
+ rmSync(dir, { recursive: true, force: true });
+ }
+});
+
+function makeTrace(overrides: Partial<RecallTraceEntry> = {}): RecallTraceEntry {
+ return {
+ schemaVersion: "1.0",
+ traceId: "trace-1",
+ ts: 1_000,
+ sessionId: "session-1",
+ sessionKey: "key-1",
+ ovSessionId: "ov-1",
+ agentId: "agent-1",
+ source: "auto_recall",
+ operationType: "semantic_find",
+ resourceTypes: ["resource", "session", "user", "agent"],
+ trigger: {
+ query: "how to inspect recall trace",
+ },
+ searches: [],
+ selected: [],
+ stats: {
+ candidateCount: 0,
+ selectedCount: 0,
+ injectedCount: 0,
+ },
+ ...overrides,
+ };
+}
+
+describe("normalizeResourceTypes()", () => {
+ it("defaults missing, empty array, and empty string to the backward-compatible memory recall set", () => {
+ expect(normalizeResourceTypes(undefined)).toEqual(["user", "agent"]);
+ expect(normalizeResourceTypes([])).toEqual(["user", "agent"]);
+ expect(normalizeResourceTypes(" ")).toEqual(["user", "agent"]);
+ });
+
+ it("normalizes comma-separated strings, trims entries, and deduplicates", () => {
+ expect(normalizeResourceTypes(" user,agent\nuser ")).toEqual(["user", "agent"]);
+ });
+
+ it("rejects unknown resource types instead of falling back to defaults", () => {
+ expect(() => normalizeResourceTypes(["user", "project"])).toThrow(
+ "invalid resourceTypes: project",
+ );
+ });
+});
+
+describe("resolveRecallSearchPlan()", () => {
+ it("builds the default backward-compatible memory recall search plan", () => {
+ const plan = resolveRecallSearchPlan(undefined, {
+ ovSessionId: "ov-session-1",
+ agentId: "agent-1",
+ });
+
+ expect(plan.searches).toEqual([
+ { resourceType: "user", targetUri: "viking://user/memories" },
+ { resourceType: "agent", targetUri: "viking://agent/memories" },
+ ]);
+ expect(plan.skipped).toEqual([]);
+ expect(plan.resourceTypes).toEqual(["user", "agent"]);
+ });
+
+ it("builds session/user/agent searches only when explicitly requested", () => {
+ const plan = resolveRecallSearchPlan(["resource", "session", "user", "agent"], {
+ ovSessionId: "ov-session-1",
+ agentId: "agent-1",
+ });
+
+ expect(plan.searches).toEqual([
+ { resourceType: "resource", targetUri: "viking://resources" },
+ { resourceType: "session", targetUri: "viking://session/ov-session-1/history" },
+ { resourceType: "user", targetUri: "viking://user/memories" },
+ { resourceType: "agent", targetUri: "viking://agent/memories" },
+ ]);
+ });
+
+ it("skips session search without failing the whole plan when ovSessionId is missing", () => {
+ const plan = resolveRecallSearchPlan(["session", "user"], { agentId: "agent-1" });
+
+ expect(plan.searches).toEqual([
+ { resourceType: "user", targetUri: "viking://user/memories" },
+ ]);
+ expect(plan.skipped).toEqual([
+ { resourceType: "session", reason: "missing_session" },
+ ]);
+ expect(plan.resourceTypes).toEqual(["session", "user"]);
+ });
+});
+
+describe("RecallTraceMemoryStore", () => {
+ it("keeps a bounded ring buffer and returns matching traces by timestamp descending", () => {
+ const store = new RecallTraceMemoryStore(2);
+ store.record(makeTrace({ traceId: "old", ts: 1, sessionId: "session-a" }));
+ store.record(makeTrace({ traceId: "newer", ts: 3, sessionId: "session-a" }));
+ store.record(makeTrace({ traceId: "new", ts: 2, sessionId: "session-a" }));
+
+ const result = store.query({ turn: "all", sessionId: "session-a", limit: 10 });
+
+ expect(result.entries.map((entry) => entry.traceId)).toEqual(["newer", "new"]);
+ });
+
+ it("supports latest, source, session identifiers, traceId, time, and resourceTypes filters", () => {
+ const store = new RecallTraceMemoryStore(10);
+ store.record(makeTrace({
+ traceId: "auto-user",
+ ts: 10,
+ source: "auto_recall",
+ sessionId: "session-a",
+ resourceTypes: ["user"],
+ }));
+ store.record(makeTrace({
+ traceId: "tool-resource",
+ ts: 20,
+ source: "ov_search",
+ sessionId: "session-b",
+ ovSessionId: "ov-b",
+ resourceTypes: ["resource"],
+ }));
+ store.record(makeTrace({
+ traceId: "auto-agent",
+ ts: 30,
+ source: "auto_recall",
+ sessionKey: "key-c",
+ resourceTypes: ["agent"],
+ }));
+
+ expect(store.query({ turn: "latest", source: "auto_recall", limit: 10 }).entries.map((e) => e.traceId))
+ .toEqual(["auto-agent"]);
+ expect(store.query({ turn: "all", ovSessionId: "ov-b", limit: 10 }).entries.map((e) => e.traceId))
+ .toEqual(["tool-resource"]);
+ expect(store.query({ turn: "all", traceId: "auto-user", limit: 10 }).entries.map((e) => e.traceId))
+ .toEqual(["auto-user"]);
+ expect(store.query({ turn: "all", since: 15, until: 35, resourceTypes: ["agent"], limit: 10 }).entries.map((e) => e.traceId))
+ .toEqual(["auto-agent"]);
+ });
+});
+
+describe("RecallTraceJsonlStore", () => {
+ it("persists traces by day and lets a new store query them after flush", async () => {
+ const dir = makeTempDir();
+ const store = new RecallTraceJsonlStore({ dir });
+ await store.append(makeTrace({ traceId: "persisted", ts: Date.UTC(2026, 5, 1), sessionId: "session-jsonl" }));
+ await store.flush();
+
+ const reloaded = new RecallTraceJsonlStore({ dir });
+ const result = await reloaded.query({ turn: "all", sessionId: "session-jsonl", limit: 10 });
+
+ expect(result.entries.map((entry) => entry.traceId)).toEqual(["persisted"]);
+ expect(result.lookupLayer).toBe("persistent");
+ expect(result.warnings).toEqual([]);
+ });
+
+ it("does not persist raw user text previews unless explicitly enabled", async () => {
+ const dir = makeTempDir();
+ const store = new RecallTraceJsonlStore({ dir });
+ await store.append(makeTrace({
+ traceId: "redacted-preview",
+ ts: Date.UTC(2026, 5, 1),
+ trigger: {
+ query: "safe query",
+ rawUserTextPreview: "private user wording",
+ },
+ }));
+ await store.flush();
+
+ const reloaded = new RecallTraceJsonlStore({ dir });
+ const result = await reloaded.query({ turn: "all", traceId: "redacted-preview", limit: 10 });
+
+ expect(result.entries[0]!.trigger.query).toBe("safe query");
+ expect(result.entries[0]!.trigger.rawUserTextPreview).toBeUndefined();
+ });
+
+ it("skips corrupted JSONL lines and returns warnings with valid entries", async () => {
+ const dir = makeTempDir();
+ writeFileSync(
+ join(dir, "1970-01-01.jsonl"),
+ [
+ "not-json",
+ JSON.stringify(makeTrace({ traceId: "valid", ts: 1_000, sessionId: "session-jsonl" })),
+ "",
+ ].join("\n"),
+ "utf8",
+ );
+
+ const store = new RecallTraceJsonlStore({ dir });
+ const result = await store.query({ turn: "all", sessionId: "session-jsonl", since: 0, until: 86_400_000, limit: 10 });
+
+ expect(result.entries.map((entry) => entry.traceId)).toEqual(["valid"]);
+ expect(result.warnings.some((warning) => warning.includes("Skipping corrupted recall trace line"))).toBe(true);
+ });
+});
+
+describe("RecallTraceRecorder", () => {
+ it("does not create a persistent directory when persistence is disabled", async () => {
+ const parent = makeTempDir();
+ const traceDir = join(parent, "disabled-traces");
+ const recorder = new RecallTraceRecorder({
+ memoryMaxEntries: 10,
+ persist: false,
+ traceDir,
+ });
+
+ recorder.record(makeTrace({ traceId: "memory-only", sessionId: "session-memory" }));
+ await recorder.flush();
+
+ expect(existsSync(traceDir)).toBe(false);
+ expect(recorder.query({ turn: "all", sessionId: "session-memory", limit: 10 }).entries.map((entry) => entry.traceId))
+ .toEqual(["memory-only"]);
+ });
+
+ it("keeps memory traces queryable when JSONL append fails", async () => {
+ const parent = makeTempDir();
+ const blockedPath = join(parent, "not-a-directory");
+ writeFileSync(blockedPath, "block mkdir", "utf8");
+ const recorder = new RecallTraceRecorder({
+ memoryMaxEntries: 10,
+ persist: true,
+ traceDir: blockedPath,
+ });
+
+ recorder.record(makeTrace({ traceId: "best-effort", sessionId: "session-memory" }));
+ const flushResult = await recorder.flush();
+
+ expect(flushResult.warnings.length).toBeGreaterThan(0);
+ expect(recorder.query({ turn: "all", sessionId: "session-memory", limit: 10 }).entries.map((entry) => entry.traceId))
+ .toEqual(["best-effort"]);
+ });
+
+ it("queries memory first and falls back to persisted traces when memory has no match", async () => {
+ const dir = makeTempDir();
+ const writer = new RecallTraceRecorder({
+ memoryMaxEntries: 10,
+ persist: true,
+ traceDir: dir,
+ });
+ writer.record(makeTrace({ traceId: "persisted-only", sessionId: "persisted-session", ts: Date.now() }));
+ await writer.flush();
+
+ const reader = new RecallTraceRecorder({
+ memoryMaxEntries: 10,
+ persist: true,
+ traceDir: dir,
+ });
+ const result = await reader.queryWithFallback({ turn: "all", sessionId: "persisted-session", limit: 10 });
+
+ expect(result.lookupLayer).toBe("persistent");
+ expect(result.entries.map((entry) => entry.traceId)).toEqual(["persisted-only"]);
+ });
+
+ it("can durably record and flush a trace before a tool returns", async () => {
+ const dir = makeTempDir();
+ const recorder = new RecallTraceRecorder({
+ memoryMaxEntries: 10,
+ persist: true,
+ traceDir: dir,
+ });
+
+ await recorder.recordAndFlush(makeTrace({
+ traceId: "durable-before-return",
+ sessionId: "durable-session",
+ ts: Date.UTC(2026, 5, 1),
+ }));
+
+ const freshReader = new RecallTraceRecorder({
+ memoryMaxEntries: 10,
+ persist: true,
+ traceDir: dir,
+ });
+ const result = await freshReader.queryWithFallback({ turn: "all", sessionId: "durable-session", limit: 10 });
+
+ expect(result.lookupLayer).toBe("persistent");
+ expect(result.entries.map((entry) => entry.traceId)).toEqual(["durable-before-return"]);
+ });
+});