Self-evolving Context Database for AI Agents. Unify Agent Memory, Knowledge RAG and Skills.
Python agent-contextagent-memoryagent-pluginsagentic-ragcontext-databasedsh-pluginknowledge-basememorymemory-managementself-evolvingvector-database
feat(openclaw): add recall trace core (#2587)
Mingjian Quee2ca85d8ec29
diff --git a/examples/openclaw-plugin/config.ts b/examples/openclaw-plugin/config.tsindex 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.jsonindex 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.tsnew file mode 100644index 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.tsindex 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.tsnew file mode 100644index 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"]);+ });+});