@openviking/openclaw-plugin 2026.6.2 → 2026.6.17-dev.2

package/plugin/openviking-memory-recall-tools.ts

@@ -0,0 +1,368 @@
+import { Type } from "@sinclair/typebox";
+
+import type { FindResult, FindResultItem } from "../client.js";
+import type { BuildMemoryLinesWithBudgetOptions } from "../auto-recall.js";
+import type { RankingOptions } from "../memory-ranking.js";
+import type { EffectiveQueryConfig, QueryConfigContext, RuntimeQueryParams } from "../query-config.js";
+import type { RecallResourceType } from "../registries/recall-resource-types.js";
+import type {
+  RecallTraceEntry,
+  RecallTraceResult,
+} from "../recall-trace.js";
+
+export type OpenVikingMemoryRecallToolContext = {
+  sessionKey?: string;
+  sessionId?: string;
+  agentId?: string;
+  senderId?: string;
+};
+
+export type OpenVikingMemoryRecallSession = {
+  sessionId?: string;
+  sessionKey?: string;
+  ovSessionId?: string;
+  agentId: string;
+};
+
+export type OpenVikingMemoryRecallClient = {
+  find: (
+    query: string,
+    options: {
+      targetUri?: string;
+      limit: number;
+      scoreThreshold: number;
+      contextType?: "memory" | "resource";
+      actorPeerId?: string;
+    },
+  ) => Promise<FindResult>;
+  read: (uri: string, agentId?: string) => Promise<string>;
+  getDefaultAgentId: () => string;
+};
+
+export type OpenVikingMemoryRecallToolsDeps = {
+  registerTool: (toolOrFactory: unknown, opts: { name: string }) => void;
+  getClient: () => Promise<OpenVikingMemoryRecallClient>;
+  queryConfigStore: {
+    getEffective: (
+      ctx: QueryConfigContext,
+      request?: RuntimeQueryParams,
+    ) => Promise<EffectiveQueryConfig>;
+  };
+  toQueryConfigContext: (session: OpenVikingMemoryRecallSession) => QueryConfigContext;
+  resolvePluginSessionRouting: (
+    ctx?: OpenVikingMemoryRecallToolContext,
+  ) => OpenVikingMemoryRecallSession;
+  isBypassedSession: (ctx?: OpenVikingMemoryRecallToolContext) => boolean;
+  makeBypassedToolResult: (toolName: string) => unknown;
+  resolveRecallSearchPlan: (
+    resourceTypes: unknown,
+    ctx: { ovSessionId?: string; agentId?: string },
+  ) => {
+    resourceTypes: RecallResourceType[];
+    searches: Array<{ resourceType: RecallResourceType; targetUri?: string; contextType: "memory" | "resource" }>;
+    skipped: Array<{ resourceType: RecallResourceType; reason: "missing_session" }>;
+  };
+  postProcessMemories: (
+    items: FindResultItem[],
+    options: { limit: number; scoreThreshold: number },
+  ) => FindResultItem[];
+  pickMemoriesForInjection: (
+    items: FindResultItem[],
+    limit: number,
+    queryText: string,
+    scoreThreshold: number,
+    rankingOptions?: RankingOptions,
+  ) => FindResultItem[];
+  buildMemoryLinesWithBudget: (
+    memories: FindResultItem[],
+    readFn: (uri: string) => Promise<string>,
+    options: BuildMemoryLinesWithBudgetOptions,
+  ) => Promise<{ lines: string[]; estimatedTokens: number }>;
+  inferRecallResourceType: (uri: string) => RecallResourceType | undefined;
+  createTraceId: (source: string) => string;
+  boundTraceQuery: (query: string, maxChars: number) => { query: string; queryTruncated?: boolean };
+  previewText: (value: unknown, maxChars: number) => string | undefined;
+  traceRecorder?: { recordAndFlush?: (entry: RecallTraceEntry) => Promise<unknown> };
+  cfg: {
+    recallTargetTypes: RecallResourceType[];
+    traceRecallMaxResultsPerSearch: number;
+    traceRecallPreviewChars: number;
+    traceRecallQueryMaxChars: number;
+    logFindRequests: boolean;
+  };
+  logger: {
+    info?: (message: string) => void;
+  };
+};
+
+function toTraceResult(
+  item: FindResultItem,
+  resultType: RecallTraceResult["resultType"],
+  deps: OpenVikingMemoryRecallToolsDeps,
+): RecallTraceResult {
+  return {
+    uri: item.uri,
+    resourceType: deps.inferRecallResourceType(item.uri),
+    category: item.category,
+    score: item.score,
+    level: item.level,
+    abstractPreview: deps.previewText(item.abstract || item.overview, deps.cfg.traceRecallPreviewChars),
+    resultType,
+  };
+}
+
+export function registerOpenVikingMemoryRecallTools(
+  deps: OpenVikingMemoryRecallToolsDeps,
+): void {
+  deps.registerTool(
+    (ctx: OpenVikingMemoryRecallToolContext) => ({
+      name: "memory_recall",
+      label: "Memory Recall (OpenViking)",
+      description:
+        "Search long-term memories from OpenViking. Use when you need past user preferences, facts, or decisions.",
+      parameters: Type.Object({
+        query: Type.String({ description: "Search query" }),
+        limit: Type.Optional(
+          Type.Number({ description: "Max results (default: plugin config)" }),
+        ),
+        scoreThreshold: Type.Optional(
+          Type.Number({ description: "Minimum score (0-1, default: plugin config)" }),
+        ),
+        targetUri: Type.Optional(
+          Type.String({ description: "Search scope URI (default: plugin config)" }),
+        ),
+        resourceTypes: Type.Optional(
+          Type.Array(Type.String({ description: "resource, user, or agent; used when targetUri is omitted" })),
+        ),
+      }),
+      async execute(_toolCallId: string, params: Record<string, unknown>) {
+        if (deps.isBypassedSession(ctx)) {
+          return deps.makeBypassedToolResult("memory_recall");
+        }
+        const session = deps.resolvePluginSessionRouting(ctx);
+        const { query } = params as { query: string };
+        const queryConfig = await deps.queryConfigStore.getEffective(deps.toQueryConfigContext(session), {
+          recallLimit: typeof (params as { limit?: number }).limit === "number" ? (params as { limit: number }).limit : undefined,
+          scoreThreshold: typeof (params as { scoreThreshold?: number }).scoreThreshold === "number" ? (params as { scoreThreshold: number }).scoreThreshold : undefined,
+          targetUri: typeof (params as { targetUri?: string }).targetUri === "string" ? (params as { targetUri: string }).targetUri : undefined,
+          resourceTypes: Object.prototype.hasOwnProperty.call(params, "resourceTypes")
+            ? (params as { resourceTypes?: unknown }).resourceTypes as RuntimeQueryParams["resourceTypes"]
+            : undefined,
+        });
+        const limit = queryConfig.recallLimit;
+        const scoreThreshold = queryConfig.scoreThreshold;
+        const targetUri =
+          typeof (params as { targetUri?: string }).targetUri === "string"
+            ? (params as { targetUri: string }).targetUri
+            : queryConfig.targetUri;
+        const requestedResourceTypes = Object.prototype.hasOwnProperty.call(params, "resourceTypes")
+          ? (params as { resourceTypes?: unknown }).resourceTypes
+          : queryConfig.resourceTypes;
+        const requestLimit = queryConfig.candidateLimit;
+
+        const recallClient = await deps.getClient();
+        if (deps.cfg.logFindRequests) {
+          deps.logger.info?.(
+            `openviking: memory_recall X-OpenViking-Actor-Peer="${session.agentId}" ` +
+              `(plugin defaultAgentId="${recallClient.getDefaultAgentId()}" is unused when session context is present)`,
+          );
+        }
+
+        let result: FindResult;
+        let memoryRecallSearches: RecallTraceEntry["searches"] = [];
+        if (targetUri) {
+          result = await recallClient.find(
+            query,
+          {
+            targetUri,
+            limit: requestLimit,
+            scoreThreshold: 0,
+            actorPeerId: session.agentId,
+          },
+        );
+          const traceResults = [
+            ...(result.memories ?? []).map((item) => toTraceResult(item, "memory", deps)),
+            ...(result.resources ?? []).map((item) => toTraceResult(item, "resource", deps)),
+          ].slice(0, deps.cfg.traceRecallMaxResultsPerSearch);
+          memoryRecallSearches = [{
+            resourceType: deps.inferRecallResourceType(targetUri) ?? "resource",
+            targetUriInput: targetUri,
+            targetUriResolved: targetUri,
+            limit: requestLimit,
+            scoreThreshold,
+            durationMs: 0,
+            total: result.total ?? traceResults.length,
+            results: traceResults,
+          }];
+        } else {
+          const searchPlan = deps.resolveRecallSearchPlan(requestedResourceTypes ?? deps.cfg.recallTargetTypes, {
+            ovSessionId: session.ovSessionId,
+            agentId: session.agentId,
+          });
+          const settled = await Promise.allSettled(searchPlan.searches.map((search) =>
+            recallClient.find(
+              query,
+              {
+                targetUri: search.targetUri,
+                limit: requestLimit,
+                scoreThreshold: 0,
+                contextType: search.contextType,
+                actorPeerId: session.agentId,
+              },
+            ),
+          ));
+          const allMemories: FindResultItem[] = [];
+          for (let index = 0; index < settled.length; index += 1) {
+            const s = settled[index]!;
+            const search = searchPlan.searches[index]!;
+            if (s.status === "fulfilled") {
+              allMemories.push(...(s.value.memories ?? []), ...(s.value.resources ?? []));
+              memoryRecallSearches.push({
+                resourceType: search.resourceType,
+                targetUriInput: search.targetUri,
+                targetUriResolved: search.targetUri,
+                limit: requestLimit,
+                scoreThreshold,
+                durationMs: 0,
+                total: s.value.total ?? ((s.value.memories ?? []).length + (s.value.resources ?? []).length),
+                results: [
+                  ...(s.value.memories ?? []).map((item) => toTraceResult(item, "memory", deps)),
+                  ...(s.value.resources ?? []).map((item) => toTraceResult(item, "resource", deps)),
+                ].slice(0, deps.cfg.traceRecallMaxResultsPerSearch),
+              });
+            } else {
+              memoryRecallSearches.push({
+                resourceType: search.resourceType,
+                targetUriInput: search.targetUri,
+                targetUriResolved: search.targetUri,
+                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) =>
+            index === self.findIndex((m) => m.uri === memory.uri)
+          );
+          const leafOnly = uniqueMemories.filter((m) => !m.level || m.level === 2);
+          result = {
+            memories: leafOnly,
+            total: leafOnly.length,
+          };
+        }
+
+        const leafOnly = (result.memories ?? []).filter((m) => !m.level || m.level === 2);
+        const processed = deps.postProcessMemories(leafOnly, {
+          limit: requestLimit,
+          scoreThreshold,
+        });
+        const memories = deps.pickMemoriesForInjection(processed, limit, query, scoreThreshold, {
+          weights: queryConfig.rankingWeights,
+          categoryWeights: queryConfig.categoryWeights,
+          resourceTypeWeights: queryConfig.resourceTypeWeights,
+        });
+        const candidateTraceResults = leafOnly
+          .map((item) => toTraceResult(item, deps.inferRecallResourceType(item.uri) === "resource" ? "resource" : "memory", deps))
+          .slice(0, deps.cfg.traceRecallMaxResultsPerSearch);
+        const traceResourceTypes = [...new Set(
+          (targetUri ? [deps.inferRecallResourceType(targetUri)] : memoryRecallSearches.map((search) => search.resourceType))
+            .filter((resourceType): resourceType is RecallResourceType => Boolean(resourceType)),
+        )];
+        const recordMemoryRecallTrace = async (injectedUris: Set<string>) => {
+          await deps.traceRecorder?.recordAndFlush?.({
+            schemaVersion: "1.0",
+            traceId: deps.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 : ["resource"],
+            trigger: deps.boundTraceQuery(query, deps.cfg.traceRecallQueryMaxChars),
+            searches: memoryRecallSearches.length > 0 ? memoryRecallSearches : [{
+              resourceType: "resource",
+              targetUriInput: targetUri,
+              targetUriResolved: targetUri ?? "viking://resources",
+              limit: requestLimit,
+              scoreThreshold,
+              durationMs: 0,
+              total: result.total ?? leafOnly.length,
+              results: candidateTraceResults,
+            }],
+            selected: memories.map((item) => ({
+              uri: item.uri,
+              resourceType: deps.inferRecallResourceType(item.uri),
+              category: item.category,
+              score: item.score,
+              abstractPreview: deps.previewText(item.abstract || item.overview, deps.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 },
+          };
+        }
+        const { lines: memoryLines } = await deps.buildMemoryLinesWithBudget(
+          memories,
+          (uri) => recallClient.read(uri, session.agentId),
+          {
+            recallPreferAbstract: false,
+            recallMaxInjectedChars: queryConfig.maxInjectedChars,
+          },
+        );
+        if (memoryLines.length === 0) {
+          await recordMemoryRecallTrace(new Set());
+          return {
+            content: [
+              {
+                type: "text",
+                text: `No complete OpenViking memories fit recallMaxInjectedChars=${queryConfig.maxInjectedChars}.`,
+              },
+            ],
+            details: {
+              count: 0,
+              memories,
+              total: result.total ?? memories.length,
+              scoreThreshold,
+              requestLimit,
+              recallMaxInjectedChars: queryConfig.maxInjectedChars,
+            },
+          };
+        }
+        await recordMemoryRecallTrace(new Set(memories.slice(0, memoryLines.length).map((item) => item.uri)));
+        return {
+          content: [
+            {
+              type: "text",
+              text: `Found ${memoryLines.length} memories:\n\n${memoryLines.join("\n")}`,
+            },
+          ],
+          details: {
+            count: memoryLines.length,
+            memories,
+            total: result.total ?? memories.length,
+            scoreThreshold,
+            requestLimit,
+            recallMaxInjectedChars: queryConfig.maxInjectedChars,
+          },
+        };
+      },
+    }),
+    { name: "memory_recall" },
+  );
+}

package/plugin/openviking-memory-tools.ts

@@ -0,0 +1,299 @@
+import { Type } from "@sinclair/typebox";
+
+import type { CommitSessionResult, FindResultItem } from "../client.js";
+import { clampScore, postProcessMemories } from "../memory-ranking.js";
+import { isMemoryUri } from "../routing/memory-uri.js";
+
+export type OpenVikingMemoryToolContext = {
+  sessionKey?: string;
+  sessionId?: string;
+  agentId?: string;
+  senderId?: string;
+  requesterSenderId?: string;
+};
+
+export type OpenVikingMemorySession = {
+  sessionId?: string;
+  sessionKey?: string;
+  ovSessionId?: string;
+  agentId: string;
+};
+
+export type OpenVikingMemoryClient = {
+  addSessionMessage: (
+    sessionId: string,
+    role: string,
+    parts: Array<{ type: "text"; text: string }>,
+    agentId?: string,
+    createdAt?: string,
+    roleId?: string,
+  ) => Promise<void>;
+  commitSession: (
+    sessionId: string,
+    options: { wait: true; agentId: string; keepRecentCount: number },
+  ) => Promise<CommitSessionResult>;
+  deleteUri: (uri: string, agentId?: string) => Promise<void>;
+  find: (
+    query: string,
+    options: { targetUri: string; limit: number; scoreThreshold: number },
+    agentId?: string,
+  ) => Promise<{ memories?: FindResultItem[] }>;
+};
+
+export type OpenVikingMemoryToolsDeps = {
+  registerTool: (toolOrFactory: unknown, opts: { name: string }) => void;
+  getClient: () => Promise<OpenVikingMemoryClient>;
+  normalizeSessionId: (sessionId: string) => string;
+  createTempSessionId: () => string;
+  extractSenderId: (ctx?: OpenVikingMemoryToolContext) => string | undefined;
+  toRoleId: (senderId?: string) => string | undefined;
+  resolvePluginSessionRouting: (ctx?: OpenVikingMemoryToolContext) => OpenVikingMemorySession;
+  isBypassedSession: (ctx?: OpenVikingMemoryToolContext) => boolean;
+  makeBypassedToolResult: (toolName: string) => unknown;
+  defaultTargetUri: string;
+  defaultRecallScoreThreshold: number;
+  logFindRequests: boolean;
+  logger: {
+    info?: (message: string) => void;
+    warn: (message: string) => void;
+  };
+};
+
+function totalCommitMemories(r: CommitSessionResult): number {
+  const m = r.memories_extracted;
+  if (!m || typeof m !== "object") return 0;
+  return Object.values(m).reduce((sum, n) => sum + (n ?? 0), 0);
+}
+
+export function registerOpenVikingMemoryTools(deps: OpenVikingMemoryToolsDeps): void {
+  deps.registerTool(
+    (ctx: OpenVikingMemoryToolContext) => ({
+      name: "memory_store",
+      label: "Memory Store (OpenViking)",
+      description:
+        "Store text in OpenViking memory pipeline by writing to a session and running memory extraction.",
+      parameters: Type.Object({
+        text: Type.String({ description: "Information to store as memory source text" }),
+        role: Type.Optional(Type.String({ description: "Session role, default user" })),
+        sessionId: Type.Optional(Type.String({ description: "Existing OpenViking session ID" })),
+      }),
+      async execute(_toolCallId: string, params: Record<string, unknown>) {
+        if (deps.isBypassedSession(ctx)) {
+          return deps.makeBypassedToolResult("memory_store");
+        }
+        const session = deps.resolvePluginSessionRouting(ctx);
+        const { text } = params as { text: string };
+        const role =
+          typeof (params as { role?: string }).role === "string"
+            ? (params as { role: string }).role
+            : "user";
+        const explicitSessionId =
+          typeof (params as { sessionId?: unknown }).sessionId === "string" &&
+          (params as { sessionId: string }).sessionId.trim()
+            ? deps.normalizeSessionId((params as { sessionId: string }).sessionId)
+            : undefined;
+
+        if (deps.logFindRequests) {
+          deps.logger.info?.(
+            `openviking: memory_store invoked (textLength=${text?.length ?? 0}, sessionId=${explicitSessionId ?? "auto"})`,
+          );
+        }
+
+        let sessionId = explicitSessionId;
+        let usedTempSession = false;
+        try {
+          const client = await deps.getClient();
+          if (!sessionId) {
+            sessionId = deps.createTempSessionId();
+            usedTempSession = true;
+          }
+          const roleId = role === "user" ? deps.toRoleId(deps.extractSenderId(ctx)) : undefined;
+          await client.addSessionMessage(
+            sessionId,
+            role,
+            [{ type: "text", text }],
+            session.agentId,
+            undefined,
+            roleId,
+          );
+          const commitResult = await client.commitSession(sessionId, {
+            wait: true,
+            agentId: session.agentId,
+            keepRecentCount: 0,
+          });
+          const memoriesCount = totalCommitMemories(commitResult);
+          if (commitResult.status === "failed") {
+            deps.logger.warn(
+              `openviking: memory_store commit failed (sessionId=${sessionId}): ${commitResult.error ?? "unknown"}`,
+            );
+            return {
+              content: [{ type: "text", text: `Memory extraction failed for session ${sessionId}: ${commitResult.error ?? "unknown"}` }],
+              details: {
+                action: "failed",
+                sessionId,
+                status: "failed",
+                error: commitResult.error,
+                usedTempSession,
+              },
+            };
+          }
+          if (commitResult.status === "timeout") {
+            deps.logger.warn(
+              `openviking: memory_store commit timed out (sessionId=${sessionId}), task_id=${commitResult.task_id ?? "none"}. Memories may still be extracting in background.`,
+            );
+            return {
+              content: [{ type: "text", text: `Memory extraction timed out for session ${sessionId}. It may still complete in the background (task_id=${commitResult.task_id ?? "none"}).` }],
+              details: {
+                action: "timeout",
+                sessionId,
+                status: "timeout",
+                taskId: commitResult.task_id,
+                usedTempSession,
+              },
+            };
+          }
+          if (memoriesCount === 0) {
+            deps.logger.warn(
+              `openviking: memory_store committed but 0 memories extracted (sessionId=${sessionId}). ` +
+                "Check OpenViking server logs for embedding/extract errors (e.g. 401 API key, or extraction pipeline).",
+            );
+          } else {
+            deps.logger.info?.(`openviking: memory_store committed, memories=${memoriesCount}`);
+          }
+          return {
+            content: [
+              {
+                type: "text",
+                text: `Stored in OpenViking session ${sessionId} and committed ${memoriesCount} memories.`,
+              },
+            ],
+            details: {
+              action: "stored",
+              sessionId,
+              memoriesCount,
+              status: commitResult.status,
+              archived: commitResult.archived ?? false,
+              usedTempSession,
+            },
+          };
+        } catch (err) {
+          deps.logger.warn(`openviking: memory_store failed: ${String(err)}`);
+          throw err;
+        }
+      },
+    }),
+    { name: "memory_store" },
+  );
+
+  deps.registerTool(
+    (ctx: OpenVikingMemoryToolContext) => ({
+      name: "memory_forget",
+      label: "Memory Forget (OpenViking)",
+      description:
+        "Forget memory by URI, or search then delete when a strong single match is found.",
+      parameters: Type.Object({
+        uri: Type.Optional(Type.String({ description: "Exact memory URI to delete" })),
+        query: Type.Optional(Type.String({ description: "Search query to find memory URI" })),
+        targetUri: Type.Optional(
+          Type.String({ description: "Search scope URI (default: plugin config)" }),
+        ),
+        limit: Type.Optional(Type.Number({ description: "Search limit (default: 5)" })),
+        scoreThreshold: Type.Optional(
+          Type.Number({ description: "Minimum score (0-1, default: plugin config)" }),
+        ),
+      }),
+      async execute(_toolCallId: string, params: Record<string, unknown>) {
+        if (deps.isBypassedSession(ctx)) {
+          return deps.makeBypassedToolResult("memory_forget");
+        }
+        const session = deps.resolvePluginSessionRouting(ctx);
+        const client = await deps.getClient();
+        const uri = (params as { uri?: string }).uri;
+        if (uri) {
+          if (!isMemoryUri(uri)) {
+            return {
+              content: [{ type: "text", text: `Refusing to delete non-memory URI: ${uri}` }],
+              details: { action: "rejected", uri },
+            };
+          }
+          await client.deleteUri(uri, session.agentId);
+          return {
+            content: [{ type: "text", text: `Forgotten: ${uri}` }],
+            details: { action: "deleted", uri },
+          };
+        }
+
+        const query = (params as { query?: string }).query;
+        if (!query) {
+          return {
+            content: [{ type: "text", text: "Provide uri or query." }],
+            details: { error: "missing_param" },
+          };
+        }
+
+        const limit =
+          typeof (params as { limit?: number }).limit === "number"
+            ? Math.max(1, Math.floor((params as { limit: number }).limit))
+            : 5;
+        const scoreThreshold =
+          typeof (params as { scoreThreshold?: number }).scoreThreshold === "number"
+            ? Math.max(0, Math.min(1, (params as { scoreThreshold: number }).scoreThreshold))
+            : deps.defaultRecallScoreThreshold;
+        const targetUri =
+          typeof (params as { targetUri?: string }).targetUri === "string"
+            ? (params as { targetUri: string }).targetUri
+            : deps.defaultTargetUri;
+        const requestLimit = Math.max(limit * 4, 20);
+
+        const result = await client.find(
+          query,
+          {
+            targetUri,
+            limit: requestLimit,
+            scoreThreshold: 0,
+          },
+          session.agentId,
+        );
+        const candidates = postProcessMemories(result.memories ?? [], {
+          limit: requestLimit,
+          scoreThreshold,
+          leafOnly: true,
+        }).filter((item) => isMemoryUri(item.uri));
+        if (candidates.length === 0) {
+          return {
+            content: [
+              {
+                type: "text",
+                text: "No matching leaf memory candidates found. Try a more specific query.",
+              },
+            ],
+            details: { action: "none", scoreThreshold },
+          };
+        }
+        const top = candidates[0];
+        if (candidates.length === 1 && clampScore(top.score) >= 0.85) {
+          await client.deleteUri(top.uri, session.agentId);
+          return {
+            content: [{ type: "text", text: `Forgotten: ${top.uri}` }],
+            details: { action: "deleted", uri: top.uri, score: top.score ?? 0 },
+          };
+        }
+
+        const list = candidates
+          .map((item) => `- ${item.uri} (${(clampScore(item.score) * 100).toFixed(0)}%)`)
+          .join("\n");
+
+        return {
+          content: [
+            {
+              type: "text",
+              text: `Found ${candidates.length} candidates. Specify uri:\n${list}`,
+            },
+          ],
+          details: { action: "candidates", candidates, scoreThreshold, requestLimit },
+        };
+      },
+    }),
+    { name: "memory_forget" },
+  );
+}