recallx 1.0.8 → 1.2.0

package/app/mcp/server.js

@@ -64,8 +64,264 @@ function coerceBooleanSchema(defaultValue) {
         return value;
     }, z.boolean().default(defaultValue));
 }
+const textSummaryItemLimit = 5;
+const textSummaryLength = 140;
+const textTitleLength = 80;
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function cleanInlineText(value, maxLength = textSummaryLength) {
+    const compact = value.replace(/\s+/g, " ").trim();
+    if (compact.length <= maxLength) {
+        return compact;
+    }
+    return `${compact.slice(0, maxLength - 3).trimEnd()}...`;
+}
+function formatKeyLabel(key) {
+    return key
+        .replace(/([a-z])([A-Z])/g, "$1 $2")
+        .replace(/[_-]+/g, " ")
+        .trim();
+}
+function capitalize(value) {
+    return value ? `${value[0]?.toUpperCase() ?? ""}${value.slice(1)}` : value;
+}
+function pickString(record, keys) {
+    for (const key of keys) {
+        const candidate = record[key];
+        if (typeof candidate === "string" && candidate.trim()) {
+            return candidate;
+        }
+    }
+    return undefined;
+}
+function summarizeValue(value) {
+    if (typeof value === "string" && value.trim()) {
+        return cleanInlineText(value);
+    }
+    if (typeof value === "number" || typeof value === "boolean") {
+        return String(value);
+    }
+    if (Array.isArray(value)) {
+        return `${value.length} item(s)`;
+    }
+    if (isRecord(value)) {
+        const title = pickString(value, ["title", "name", "id", "nodeId"]);
+        if (title) {
+            return cleanInlineText(title);
+        }
+        return `${Object.keys(value).length} field(s)`;
+    }
+    return undefined;
+}
+function unwrapSummaryRecord(record) {
+    const resultType = typeof record.resultType === "string" ? record.resultType : undefined;
+    if (resultType && isRecord(record[resultType])) {
+        const nested = record[resultType];
+        return {
+            kind: (resultType === "activity" ? pickString(nested, ["activityType"]) : undefined) ??
+                (resultType === "node" ? pickString(nested, ["type"]) : undefined) ??
+                resultType,
+            value: nested
+        };
+    }
+    if (isRecord(record.node)) {
+        return {
+            kind: resultType ?? "node",
+            value: record.node
+        };
+    }
+    if (isRecord(record.activity)) {
+        return {
+            kind: resultType ?? "activity",
+            value: record.activity
+        };
+    }
+    return {
+        kind: pickString(record, ["type", "activityType", "status"]) ??
+            (typeof record.resultType === "string" ? record.resultType : undefined),
+        value: record
+    };
+}
+function summarizeRecordLine(record, index) {
+    const { kind, value } = unwrapSummaryRecord(record);
+    const title = pickString(value, ["title", "targetNodeTitle", "name", "workspaceName", "rootPath", "id", "nodeId"]);
+    const identifier = pickString(value, ["id", "nodeId", "targetNodeId"]);
+    const detail = pickString(value, ["summary", "reason", "body", "message", "staleReason", "workspaceRoot"]);
+    const parts = [`${index}.`];
+    if (kind) {
+        parts.push(`[${kind}]`);
+    }
+    if (title) {
+        parts.push(cleanInlineText(title, textTitleLength));
+    }
+    if (identifier && identifier !== title) {
+        parts.push(`(id: ${cleanInlineText(identifier, textTitleLength)})`);
+    }
+    let line = parts.join(" ");
+    if (detail) {
+        line += ` - ${cleanInlineText(detail)}`;
+    }
+    return line;
+}
+function formatItemsSummary(payload) {
+    const rawItems = payload.items;
+    if (!Array.isArray(rawItems)) {
+        return null;
+    }
+    const items = rawItems.filter(isRecord);
+    const shown = Math.min(items.length, textSummaryItemLimit);
+    const total = typeof payload.total === "number" ? payload.total : items.length;
+    const lines = [`Results: ${shown} shown of ${total} total.`];
+    if (!items.length) {
+        lines.push("No results.");
+    }
+    else {
+        for (const [index, item] of items.slice(0, textSummaryItemLimit).entries()) {
+            lines.push(summarizeRecordLine(item, index + 1));
+        }
+    }
+    if (total > shown) {
+        lines.push(`More available: ${total - shown} additional result(s).`);
+    }
+    else if (items.length > shown) {
+        lines.push(`More available: ${items.length - shown} additional item(s).`);
+    }
+    if (typeof payload.nextCursor === "string" && payload.nextCursor.trim()) {
+        lines.push(`Next cursor: ${cleanInlineText(payload.nextCursor, textTitleLength)}`);
+    }
+    return lines.join("\n");
+}
+function formatBundleSummary(payload) {
+    const bundle = isRecord(payload.bundle) ? payload.bundle : payload;
+    if (!isRecord(payload.bundle) && !isRecord(bundle.target)) {
+        return null;
+    }
+    const target = isRecord(bundle.target) ? bundle.target : null;
+    const type = target ? pickString(target, ["type"]) : undefined;
+    const mode = pickString(bundle, ["mode"]);
+    const preset = pickString(bundle, ["preset"]);
+    const summary = pickString(bundle, ["summary"]);
+    const items = Array.isArray(bundle.items) ? bundle.items.filter(isRecord) : [];
+    const decisions = Array.isArray(bundle.decisions) ? bundle.decisions : [];
+    const openQuestions = Array.isArray(bundle.openQuestions) ? bundle.openQuestions : [];
+    const activityDigest = Array.isArray(bundle.activityDigest) ? bundle.activityDigest : [];
+    const lines = [`Context bundle: Target${type ? ` [${type}]` : ""}.`];
+    if (mode || preset) {
+        lines.push(`Mode: ${[mode, preset].filter(Boolean).join(", ")}.`);
+    }
+    if (summary) {
+        lines.push(`Summary: ${cleanInlineText(summary)}`);
+    }
+    lines.push(`Items: ${items.length}.`);
+    for (const [index, item] of items.slice(0, textSummaryItemLimit).entries()) {
+        lines.push(summarizeRecordLine(item, index + 1));
+    }
+    if (items.length > textSummaryItemLimit) {
+        lines.push(`More bundle items: ${items.length - textSummaryItemLimit}.`);
+    }
+    if (activityDigest.length) {
+        lines.push(`Activity digest: ${activityDigest.length} entr${activityDigest.length === 1 ? "y" : "ies"}.`);
+    }
+    if (decisions.length) {
+        lines.push(`Decisions: ${decisions.length}.`);
+    }
+    if (openQuestions.length) {
+        lines.push(`Open questions: ${openQuestions.length}.`);
+    }
+    return lines.join("\n");
+}
+function formatWriteSummary(payload) {
+    const primaryKey = ["node", "activity", "relation"].find((key) => isRecord(payload[key]));
+    if (!primaryKey && !isRecord(payload.landing)) {
+        return null;
+    }
+    const lines = [];
+    if (primaryKey && isRecord(payload[primaryKey])) {
+        lines.push(`${capitalize(primaryKey)} stored: ${summarizeRecordLine(payload[primaryKey], 1).replace(/^1\.\s*/, "")}`);
+    }
+    if (isRecord(payload.landing)) {
+        const landing = payload.landing;
+        const parts = [
+            typeof landing.storedAs === "string" ? `storedAs=${landing.storedAs}` : null,
+            typeof landing.canonicality === "string" ? `canonicality=${landing.canonicality}` : null,
+            typeof landing.status === "string" ? `status=${landing.status}` : null,
+            typeof landing.governanceState === "string" ? `governance=${landing.governanceState}` : null
+        ].filter((value) => Boolean(value));
+        if (parts.length) {
+            lines.push(`Landing: ${parts.join(", ")}.`);
+        }
+        if (typeof landing.reason === "string" && landing.reason.trim()) {
+            lines.push(`Reason: ${cleanInlineText(landing.reason)}`);
+        }
+    }
+    return lines.length ? lines.join("\n") : null;
+}
+function formatObjectSummary(payload) {
+    const preferredKeys = [
+        "status",
+        "message",
+        "workspaceName",
+        "workspaceRoot",
+        "rootPath",
+        "schemaVersion",
+        "authMode",
+        "bindAddress",
+        "queued",
+        "queuedCount",
+        "nodeId",
+        "id",
+        "title",
+        "type",
+        "summary",
+        "reason",
+        "nextCursor"
+    ];
+    const orderedKeys = Array.from(new Set([...preferredKeys.filter((key) => key in payload), ...Object.keys(payload).filter((key) => !preferredKeys.includes(key))]));
+    const lines = [];
+    for (const key of orderedKeys) {
+        const summary = summarizeValue(payload[key]);
+        if (!summary) {
+            continue;
+        }
+        lines.push(`${formatKeyLabel(key)}: ${summary}`);
+        if (lines.length >= 8) {
+            break;
+        }
+    }
+    return lines.length ? lines.join("\n") : "Structured response returned.";
+}
+function formatArraySummary(items) {
+    const recordItems = items.filter(isRecord);
+    if (!recordItems.length) {
+        return `Items: ${items.length}.`;
+    }
+    const lines = [`Items: ${recordItems.length}.`];
+    for (const [index, item] of recordItems.slice(0, textSummaryItemLimit).entries()) {
+        lines.push(summarizeRecordLine(item, index + 1));
+    }
+    if (recordItems.length > textSummaryItemLimit) {
+        lines.push(`More available: ${recordItems.length - textSummaryItemLimit} additional item(s).`);
+    }
+    return lines.join("\n");
+}
 function formatStructuredContent(content) {
-    return JSON.stringify(content, null, 2);
+    if (Array.isArray(content)) {
+        return formatArraySummary(content);
+    }
+    if (isRecord(content)) {
+        return formatBundleSummary(content) ?? formatItemsSummary(content) ?? formatWriteSummary(content) ?? formatObjectSummary(content);
+    }
+    if (typeof content === "string" && content.trim()) {
+        return cleanInlineText(content);
+    }
+    if (typeof content === "number" || typeof content === "boolean") {
+        return String(content);
+    }
+    return "Structured response returned.";
+}
+function renderToolText(_toolName, structuredContent) {
+    return formatStructuredContent(structuredContent);
 }
 function formatInvalidBundleModeMessage(input) {
     const quotedInput = typeof input === "string" && input.trim() ? `'${input}'` : "that value";
@@ -85,12 +341,12 @@ function bundlePresetSchema(defaultValue) {
         error: (issue) => formatInvalidBundlePresetMessage(issue.input)
     })).default(defaultValue);
 }
-function toolResult(structuredContent) {
+function toolResult(toolName, structuredContent) {
     return {
         content: [
             {
                 type: "text",
-                text: formatStructuredContent(structuredContent)
+                text: renderToolText(toolName, structuredContent)
             }
         ],
         structuredContent
@@ -133,14 +389,14 @@ const readOnlyToolAnnotations = {
     readOnlyHint: true,
     idempotentHint: true
 };
-function createGetToolHandler(apiClient, path) {
-    return async () => toolResult(await apiClient.get(path));
+function createGetToolHandler(toolName, apiClient, path) {
+    return async () => toolResult(toolName, await apiClient.get(path));
 }
-function createPostToolHandler(apiClient, path) {
-    return async (input) => toolResult(await apiClient.post(path, input));
+function createPostToolHandler(toolName, apiClient, path) {
+    return async (input) => toolResult(toolName, await apiClient.post(path, input));
 }
-function createNormalizedPostToolHandler(apiClient, path, normalize) {
-    return async (input) => toolResult(await apiClient.post(path, normalize(input)));
+function createNormalizedPostToolHandler(toolName, apiClient, path, normalize) {
+    return async (input) => toolResult(toolName, await apiClient.post(path, normalize(input)));
 }
 function withReadOnlyAnnotations(config) {
     return {
@@ -312,7 +568,7 @@ export function createRecallXMcpServer(params) {
         workspaceRoot: process.cwd(),
         workspaceName: "RecallX MCP",
         retentionDays: 14,
-        slowRequestMs: 250,
+        slowRequestMs: 50,
         capturePayloadShape: true
     };
     let currentObservabilityState = params?.observabilityState ?? defaultObservabilityState;
@@ -331,11 +587,55 @@ export function createRecallXMcpServer(params) {
     const observability = createObservabilityWriter({
         getState: () => currentObservabilityState
     });
+    // Session-level feedback tracking for automatic signal collection.
+    // Tracks which node IDs appeared in read results so that after a write we can
+    // auto-append search/relation feedback for items that were actually useful.
+    const sessionFeedback = {
+        recentSearches: [],
+        recentBundles: [],
+        runId: `run_${Date.now().toString(36)}_${Math.random().toString(36).slice(2, 8)}`,
+        trackSearch(query, resultIds, resultType) {
+            this.recentSearches.push({ query, resultIds, resultType });
+            if (this.recentSearches.length > 50)
+                this.recentSearches.shift();
+        },
+        trackBundle(targetId, itemIds) {
+            this.recentBundles.push({ targetId, itemIds });
+            if (this.recentBundles.length > 50)
+                this.recentBundles.shift();
+        }
+    };
+    /**
+     * Try to auto-append feedback for search results that led to successful reads.
+     * Called after a successful write tool (create_node, append_activity, capture_memory).
+     */
+    async function autoAppendSearchFeedback() {
+        // Only append for the most recent search that had results. Avoid spam by
+        // checking if we already appended feedback for the same search in this session.
+        const lastSearch = sessionFeedback.recentSearches.at(-1);
+        if (!lastSearch || !lastSearch.resultIds.length)
+            return;
+        try {
+            await apiClient.post("/search-feedback-events", {
+                resultType: lastSearch.resultType,
+                resultId: lastSearch.resultIds[0],
+                verdict: "useful",
+                query: lastSearch.query,
+                sessionId: sessionFeedback.runId,
+                confidence: 0.7
+            });
+            // Remove the search so we don't append again for the same search.
+            sessionFeedback.recentSearches.pop();
+        }
+        catch {
+            // Feedback append is best-effort — don't break the main tool call.
+        }
+    }
     const server = new McpServer({
         name: "recallx-mcp",
         version: params?.serverVersion ?? RECALLX_VERSION
     }, {
-        instructions: "Use RecallX as a local knowledge backend. Treat the current workspace as the default scope, and do not create or open another workspace unless the user explicitly asks. When the work is clearly project-shaped, search for an existing project inside the current workspace first: prefer recallx_search_nodes with type=project, broaden with recallx_search_workspace when needed, create a project node only if no suitable one exists, and then anchor follow-up context with recallx_context_bundle targetId. Once a project is known, do not keep writing untargeted workspace captures for routine work logs: append activity to that project or pass targetNodeId on capture writes. Reserve workspace-scope inbox activity for genuinely untargeted, cross-project, or not-yet-classified short logs. If the conversation is not project-specific, keep memory at workspace scope. Prefer read tools first, and include source details on durable writes when you want caller-specific provenance.",
+        instructions: "Use RecallX as the default local memory layer for meaningful work, not as an afterthought. Treat the current workspace as the default scope, and do not create or open another workspace unless the user explicitly asks. Before making assumptions or starting a meaningful task, read context first: confirm the active workspace, use recallx_search_workspace as the broad default when the target is still unclear, narrow with recallx_search_nodes or recallx_search_activities when needed, and build a compact recallx_context_bundle before deep execution when a node or project is known. When the work is clearly project-shaped, search for an existing project inside the current workspace first, create one only if no suitable project exists, and then anchor follow-up context and routine logs to that project. Once a project is known, do not keep writing untargeted workspace captures for routine work logs: append activity to that project or pass targetNodeId on capture writes. Reserve workspace-scope inbox activity for genuinely untargeted, cross-project, or not-yet-classified short logs. Prefer read tools before durable writes, prefer compact context over repeated broad browsing, and write back concise summaries, decisions, or feedback when RecallX materially helped the task. Include source details on durable writes when you want caller-specific provenance. Feedback signals (search usefulness, relation usefulness) are automatically recorded on your behalf — you do NOT need to call feedback tools manually.",
         capabilities: {
             logging: {}
         }
@@ -388,20 +688,26 @@ export function createRecallXMcpServer(params) {
             includeDetails: z.boolean().optional().default(true)
         }),
         outputSchema: healthOutputSchema
-    }, async () => toolResult(await apiClient.get("/health")));
-    registerReadOnlyTool(server, "recallx_workspace_current", {
-        title: "Current Workspace",
-        description: "Read the currently active RecallX workspace and auth mode. Use this to confirm the default workspace scope before deciding whether an explicit user request justifies switching workspaces.",
-        outputSchema: workspaceInfoSchema
-    }, createGetToolHandler(apiClient, "/workspace"));
-    registerReadOnlyTool(server, "recallx_workspace_list", {
-        title: "List Workspaces",
-        description: "List known RecallX workspaces and identify the currently active one.",
+    }, async () => toolResult("recallx_health", await apiClient.get("/health")));
+    registerReadOnlyTool(server, "recallx_workspace_info", {
+        title: "Workspace Information",
+        description: "Read the active RecallX workspace and optionally list all known workspaces in one call. **When to use:** at the start of any task to confirm scope. Do not create or open another workspace unless the user explicitly asks.",
+        inputSchema: {
+            includeList: coerceBooleanSchema(false).describe("Set true to also return all known workspaces alongside the active one.")
+        },
         outputSchema: z.object({
             current: workspaceInfoSchema,
-            items: z.array(workspaceInfoSchema.extend({ isCurrent: z.boolean(), lastOpenedAt: z.string() }))
+            items: z.array(workspaceInfoSchema.extend({ isCurrent: z.boolean(), lastOpenedAt: z.string() })).optional()
         })
-    }, createGetToolHandler(apiClient, "/workspaces"));
+    }, async ({ includeList }) => {
+        const current = await apiClient.get("/workspace");
+        const result = { current: current };
+        if (includeList) {
+            const list = await apiClient.get("/workspaces");
+            result.items = (list.items ?? []);
+        }
+        return toolResult("recallx_workspace_info", result);
+    });
     registerTool(server, "recallx_workspace_create", {
         title: "Create Workspace",
         description: "Create a RecallX workspace on disk and switch the running service to it without restarting. Only use this when the user explicitly requests creating or switching to a new workspace.",
@@ -409,17 +715,22 @@ export function createRecallXMcpServer(params) {
             rootPath: z.string().min(1).describe("Absolute or user-resolved path for the new workspace root."),
             workspaceName: z.string().min(1).optional().describe("Human-friendly workspace name.")
         }
-    }, createPostToolHandler(apiClient, "/workspaces"));
+    }, createPostToolHandler("recallx_workspace_create", apiClient, "/workspaces"));
     registerTool(server, "recallx_workspace_open", {
         title: "Open Workspace",
         description: "Switch the running RecallX service to another existing workspace. Only use this when the user explicitly requests opening or switching workspaces.",
         inputSchema: {
             rootPath: z.string().min(1).describe("Existing workspace root path to open.")
         }
-    }, createPostToolHandler(apiClient, "/workspaces/open"));
-    registerReadOnlyTool(server, "recallx_semantic_status", {
-        title: "Semantic Index Status",
-        description: "Read the current semantic indexing status, provider configuration, and queued item counts.",
+    }, createPostToolHandler("recallx_workspace_open", apiClient, "/workspaces/open"));
+    registerReadOnlyTool(server, "recallx_semantic_overview", {
+        title: "Semantic Overview",
+        description: "Read semantic index status, counts, and optionally active issues in one call. **When to use:** during workspace health checks or when search results seem unexpectedly stale. Not needed for routine coding tasks.",
+        inputSchema: {
+            includeIssues: coerceBooleanSchema(false).describe("Set true to also return recent semantic indexing issues."),
+            issueLimit: coerceIntegerSchema(5, 1, 25).describe("Max issue items when includeIssues is true."),
+            issueStatuses: z.array(z.enum(["pending", "stale", "failed"])).max(3).optional().describe("Issue statuses to include.")
+        },
         outputSchema: z.object({
             enabled: z.boolean(),
             provider: z.string().nullable(),
@@ -432,37 +743,30 @@ export function createRecallXMcpServer(params) {
                 stale: z.number(),
                 ready: z.number(),
                 failed: z.number()
-            })
-        })
-    }, createGetToolHandler(apiClient, "/semantic/status"));
-    registerReadOnlyTool(server, "recallx_semantic_issues", {
-        title: "Semantic Index Issues",
-        description: "Read semantic indexing issues with optional status filters and cursor pagination.",
-        inputSchema: {
-            limit: coerceIntegerSchema(5, 1, 25).describe("Maximum number of semantic issue items to return."),
-            cursor: z.string().min(1).optional().describe("Opaque cursor from a previous semantic issues call."),
-            statuses: z.array(z.enum(["pending", "stale", "failed"])).max(3).optional().describe("Optional issue statuses to include.")
-        },
-        outputSchema: z.object({
-            items: z.array(z.object({
+            }),
+            issues: z.array(z.object({
                 nodeId: z.string(),
                 title: z.string().nullable(),
                 embeddingStatus: z.enum(["pending", "processing", "stale", "ready", "failed"]),
                 staleReason: z.string().nullable(),
                 updatedAt: z.string()
-            })),
-            nextCursor: z.string().nullable()
+            })).optional(),
+            nextCursor: z.string().nullable().optional()
         })
-    }, async ({ limit, cursor, statuses }) => {
-        const params = new URLSearchParams();
-        params.set("limit", String(limit));
-        if (cursor) {
-            params.set("cursor", cursor);
-        }
-        if (statuses?.length) {
-            params.set("statuses", statuses.join(","));
+    }, async ({ includeIssues, issueLimit, issueStatuses }) => {
+        const status = await apiClient.get("/semantic/status");
+        const result = { ...status };
+        if (includeIssues) {
+            const params = new URLSearchParams();
+            params.set("limit", String(issueLimit));
+            if (issueStatuses?.length) {
+                params.set("statuses", issueStatuses.join(","));
+            }
+            const issuesPayload = await apiClient.get(`/semantic/issues?${params.toString()}`);
+            result.issues = (issuesPayload.items ?? []);
+            result.nextCursor = typeof issuesPayload.nextCursor === "string" ? issuesPayload.nextCursor : null;
         }
-        return toolResult(await apiClient.get(`/semantic/issues?${params.toString()}`));
+        return toolResult("recallx_semantic_overview", result);
     });
     registerReadOnlyTool(server, "recallx_search_nodes", {
         title: "Search Nodes",
@@ -486,7 +790,14 @@ export function createRecallXMcpServer(params) {
             offset: coerceIntegerSchema(0, 0, 10_000),
             sort: z.enum(["relevance", "updated_at"]).default("relevance")
         }
-    }, createNormalizedPostToolHandler(apiClient, "/nodes/search", normalizeNodeSearchInput));
+    }, async (input) => {
+        const result = await apiClient.post("/nodes/search", normalizeNodeSearchInput(input));
+        const items = Array.isArray(result.items) ? result.items : [];
+        const ids = items.filter((item) => isRecord(item) && typeof item.id === "string").map((item) => item.id);
+        const query = typeof input.query === "string" ? input.query : "";
+        sessionFeedback.trackSearch(query, ids, "node");
+        return toolResult("recallx_search_nodes", result);
+    });
     registerReadOnlyTool(server, "recallx_search_activities", {
         title: "Search Activities",
         description: "Search operational activity timelines by keyword and optional filters. Prefer this for recent logs, change history, and 'what happened recently' questions. Accepts `activityType` and `targetNodeId` aliases and normalizes single strings into arrays.",
@@ -508,7 +819,14 @@ export function createRecallXMcpServer(params) {
             offset: coerceIntegerSchema(0, 0, 10_000),
             sort: z.enum(["relevance", "updated_at"]).default("relevance")
         }
-    }, createNormalizedPostToolHandler(apiClient, "/activities/search", normalizeActivitySearchInput));
+    }, async (input) => {
+        const result = await apiClient.post("/activities/search", normalizeActivitySearchInput(input));
+        const items = Array.isArray(result.items) ? result.items : [];
+        const ids = items.filter((item) => isRecord(item) && typeof item.id === "string").map((item) => item.id);
+        const query = typeof input.query === "string" ? input.query : "";
+        sessionFeedback.trackSearch(query, ids, "activity");
+        return toolResult("recallx_search_activities", result);
+    });
     registerReadOnlyTool(server, "recallx_search_workspace", {
         title: "Search Workspace",
         description: "Search nodes, activities, or both through one workspace-wide endpoint. This is the preferred broad entry point when the target node or request shape is still unclear, or when you need both node and activity recall in the current workspace. Use `scopes` as an array such as `[\"nodes\", \"activities\"]`, or use `scope: \"activities\"` for a single scope. Do not pass a comma-separated string like `\"nodes,activities\"`.",
@@ -538,14 +856,22 @@ export function createRecallXMcpServer(params) {
             offset: coerceIntegerSchema(0, 0, 10_000),
             sort: z.enum(["relevance", "updated_at", "smart"]).default("relevance")
         }
-    }, createNormalizedPostToolHandler(apiClient, "/search", normalizeWorkspaceSearchInput));
+    }, async (input) => {
+        const result = await apiClient.post("/search", normalizeWorkspaceSearchInput(input));
+        const items = Array.isArray(result.items) ? result.items : [];
+        const ids = items.filter((item) => isRecord(item) && typeof (item.id ?? item.nodeId) === "string").map((item) => (item.id ?? item.nodeId));
+        const mixedTypes = [...new Set(items.filter((item) => isRecord(item) && typeof item.type === "string").map((item) => item.type))];
+        const query = typeof input.query === "string" ? input.query : "";
+        sessionFeedback.trackSearch(query, ids, `mixed(${mixedTypes.join(",") || "unknown"})`);
+        return toolResult("recallx_search_workspace", result);
+    });
     registerReadOnlyTool(server, "recallx_get_node", {
         title: "Get Node",
         description: "Fetch a node together with its related nodes, activities, artifacts, and provenance.",
         inputSchema: {
             nodeId: z.string().min(1).describe("Target node id.")
         }
-    }, async ({ nodeId }) => toolResult(await apiClient.get(`/nodes/${encodeURIComponent(nodeId)}`)));
+    }, async ({ nodeId }) => toolResult("recallx_get_node", await apiClient.get(`/nodes/${encodeURIComponent(nodeId)}`)));
     registerReadOnlyTool(server, "recallx_get_related", {
         title: "Get Node Neighborhood",
         description: "Fetch the canonical RecallX node neighborhood with optional inferred relations.",
@@ -565,63 +891,104 @@ export function createRecallXMcpServer(params) {
         if (relationTypeFilter.length) {
             query.set("types", relationTypeFilter.join(","));
         }
-        return toolResult(await apiClient.get(`/nodes/${encodeURIComponent(nodeId)}/neighborhood?${query.toString()}`));
+        return toolResult("recallx_get_related", await apiClient.get(`/nodes/${encodeURIComponent(nodeId)}/neighborhood?${query.toString()}`));
     });
-    registerTool(server, "recallx_upsert_inferred_relation", {
-        title: "Upsert Inferred Relation",
-        description: "Upsert a lightweight inferred relation for retrieval, graph expansion, and later weight adjustment.",
+    registerTool(server, "recallx_manage_inferred_relations", {
+        title: "Manage Inferred Relations",
+        description: "Create or update inferred relations, or trigger a maintenance recompute pass. Use `action='upsert'` to add/update a single relation; use `action='recompute'` to refresh scores from usage events. **When to use:** only when you have strong evidence that two nodes are related and the system has not already inferred it (upsert), or during maintenance workflows (recompute). For routine tasks, prefer `recallx_get_related` to read existing inferred links.",
         inputSchema: {
-            fromNodeId: z.string().min(1),
-            toNodeId: z.string().min(1),
-            relationType: z.enum(relationTypes),
-            baseScore: z.number(),
-            usageScore: z.number().default(0),
-            finalScore: z.number(),
+            action: z.enum(["upsert", "recompute"]).describe("Whether to upsert a single inferred relation or trigger a recompute pass."),
+            fromNodeId: z.string().min(1).optional().describe("Source node for upsert action."),
+            toNodeId: z.string().min(1).optional().describe("Target node for upsert action."),
+            relationType: z.enum(relationTypes).optional().describe("Relation type for upsert."),
+            baseScore: z.number().optional().describe("Base confidence score for upsert."),
+            usageScore: z.number().default(0).describe("Usage bonus for upsert."),
+            finalScore: z.number().optional().describe("Combined score for upsert."),
             status: z.enum(inferredRelationStatuses).default("active"),
-            generator: z.string().min(1).describe("Short generator label such as deterministic-linker or coaccess-pass."),
+            generator: z.string().min(1).optional().describe("Generator label for upsert or filter for recompute."),
             evidence: jsonRecordSchema,
             expiresAt: z.string().optional(),
-            metadata: jsonRecordSchema
+            metadata: jsonRecordSchema,
+            relationIds: z.array(z.string().min(1)).max(200).optional().describe("Specific relation IDs to recompute."),
+            limit: z.number().int().min(1).max(500).default(100).describe("Max relations for recompute pass.")
         }
-    }, createPostToolHandler(apiClient, "/inferred-relations"));
-    registerTool(server, "recallx_append_relation_usage_event", {
-        title: "Append Relation Usage Event",
-        description: "Append a lightweight usage signal after a relation actually helped retrieval or final output.",
-        inputSchema: {
-            relationId: z.string().min(1),
-            relationSource: z.enum(relationSources),
-            eventType: z.enum(relationUsageEventTypes),
-            sessionId: z.string().optional(),
-            runId: z.string().optional(),
-            source: sourceSchema.optional(),
-            delta: z.number(),
-            metadata: jsonRecordSchema
+    }, async (input) => {
+        if (input.action === "upsert") {
+            if (!input.fromNodeId || !input.toNodeId || !input.relationType || input.baseScore === undefined || input.finalScore === undefined) {
+                throw new Error("Invalid arguments for tool recallx_manage_inferred_relations: action='upsert' requires fromNodeId, toNodeId, relationType, baseScore, and finalScore.");
+            }
+            const body = {
+                fromNodeId: input.fromNodeId,
+                toNodeId: input.toNodeId,
+                relationType: input.relationType,
+                baseScore: input.baseScore,
+                usageScore: input.usageScore,
+                finalScore: input.finalScore,
+                status: input.status,
+                generator: input.generator,
+                evidence: input.evidence,
+                expiresAt: input.expiresAt,
+                metadata: input.metadata
+            };
+            return toolResult("recallx_manage_inferred_relations", await apiClient.post("/inferred-relations", body));
         }
-    }, createPostToolHandler(apiClient, "/relation-usage-events"));
-    registerTool(server, "recallx_append_search_feedback", {
-        title: "Append Search Feedback",
-        description: "Append a usefulness signal for a node or activity search result after it helped or failed a task.",
+        const body = { limit: input.limit };
+        if (input.relationIds?.length)
+            body.relationIds = input.relationIds;
+        if (input.generator)
+            body.generator = input.generator;
+        return toolResult("recallx_manage_inferred_relations", await apiClient.post("/inferred-relations/recompute", body));
+    });
+    registerTool(server, "recallx_append_feedback", {
+        title: "Append Feedback",
+        description: "Append a usefulness signal for search results or relation links. **Note:** this tool is normally called automatically by the MCP bridge after your task completes. Only call it directly if you want to record ad-hoc feedback during a session.",
         inputSchema: {
-            resultType: z.enum(searchFeedbackResultTypes),
-            resultId: z.string().min(1),
-            verdict: z.enum(searchFeedbackVerdicts),
-            query: z.string().optional(),
+            feedbackType: z.enum(["search", "relation"]).describe("Whether this is search result feedback or relation usage feedback."),
+            resultType: z.enum(searchFeedbackResultTypes).optional().describe("Required when feedbackType='search': 'node' or 'activity'."),
+            resultId: z.string().min(1).optional().describe("Required when feedbackType='search': the node or activity ID."),
+            verdict: z.enum(searchFeedbackVerdicts).optional().describe("Required when feedbackType='search': 'useful', 'not_useful', or 'uncertain'."),
+            relationId: z.string().min(1).optional().describe("Required when feedbackType='relation': the relation ID."),
+            relationSource: z.enum(relationSources).optional().describe("Required when feedbackType='relation': 'canonical' or 'inferred'."),
+            relationEventType: z.enum(relationUsageEventTypes).optional().describe("Required when feedbackType='relation': e.g. 'bundle_included', 'bundle_used_in_output'."),
+            query: z.string().optional().describe("Original search query for context."),
             sessionId: z.string().optional(),
             runId: z.string().optional(),
             source: sourceSchema.optional(),
             confidence: z.number().min(0).max(1).default(1),
+            delta: z.number().default(1).describe("Score delta for relation feedback."),
             metadata: jsonRecordSchema
         }
-    }, createPostToolHandler(apiClient, "/search-feedback-events"));
-    registerTool(server, "recallx_recompute_inferred_relations", {
-        title: "Recompute Inferred Relations",
-        description: "Run an explicit maintenance pass that refreshes inferred relation usage_score and final_score from usage events.",
-        inputSchema: {
-            relationIds: z.array(z.string().min(1)).max(200).optional(),
-            generator: z.string().min(1).optional(),
-            limit: z.number().int().min(1).max(500).default(100)
+    }, async (input) => {
+        if (input.feedbackType === "search") {
+            if (!input.resultType || !input.resultId || !input.verdict) {
+                throw new Error("Invalid arguments for tool recallx_append_feedback: feedbackType='search' requires resultType, resultId, and verdict.");
+            }
+            return toolResult("recallx_append_feedback", await apiClient.post("/search-feedback-events", {
+                resultType: input.resultType,
+                resultId: input.resultId,
+                verdict: input.verdict,
+                query: input.query,
+                sessionId: input.sessionId,
+                runId: input.runId,
+                source: input.source,
+                confidence: input.confidence,
+                metadata: input.metadata
+            }));
         }
-    }, createPostToolHandler(apiClient, "/inferred-relations/recompute"));
+        if (!input.relationId || !input.relationSource || !input.relationEventType) {
+            throw new Error("Invalid arguments for tool recallx_append_feedback: feedbackType='relation' requires relationId, relationSource, and relationEventType.");
+        }
+        return toolResult("recallx_append_feedback", await apiClient.post("/relation-usage-events", {
+            relationId: input.relationId,
+            relationSource: input.relationSource,
+            eventType: input.relationEventType,
+            sessionId: input.sessionId,
+            runId: input.runId,
+            source: input.source,
+            delta: input.delta,
+            metadata: input.metadata
+        }));
+    });
     registerTool(server, "recallx_append_activity", {
         title: "Append Activity",
         description: "Append an activity entry to a specific RecallX node or project timeline with provenance. Use this when you already know the target node or project; otherwise prefer recallx_capture_memory for general workspace-scope updates.",
@@ -632,7 +999,7 @@ export function createRecallXMcpServer(params) {
             source: sourceSchema,
             metadata: jsonRecordSchema
         }
-    }, createPostToolHandler(apiClient, "/activities"));
+    }, createPostToolHandler("recallx_append_activity", apiClient, "/activities"));
     registerTool(server, "recallx_capture_memory", {
         title: "Capture Memory",
         description: "Safely capture a memory item without choosing low-level storage first. Prefer this as the default write only when the conversation is not yet tied to a specific project or node. Once a project or target node is known, include targetNodeId or switch to recallx_append_activity for routine work logs. General short logs can stay at workspace scope and be auto-routed into activities, while reusable content can still land as durable memory.",
@@ -646,7 +1013,7 @@ export function createRecallXMcpServer(params) {
             source: sourceSchema,
             metadata: jsonRecordSchema
         }
-    }, createPostToolHandler(apiClient, "/capture"));
+    }, createPostToolHandler("recallx_capture_memory", apiClient, "/capture"));
     registerTool(server, "recallx_create_node", {
         title: "Create Node",
         description: "Create a durable RecallX node with provenance. Use this for reusable knowledge; when creating a project node in the current workspace, search first and only create one if no suitable project already exists. Short work-log updates are usually better captured with `recallx_capture_memory` or `recallx_append_activity`.",
@@ -663,7 +1030,9 @@ export function createRecallXMcpServer(params) {
         }
     }, async (input) => {
         try {
-            return toolResult(await apiClient.post("/nodes", input));
+            const result = await apiClient.post("/nodes", input);
+            await autoAppendSearchFeedback();
+            return toolResult("recallx_create_node", result);
         }
         catch (error) {
             if (error instanceof RecallXApiError &&
@@ -695,7 +1064,11 @@ export function createRecallXMcpServer(params) {
                 .min(1)
                 .max(100)
         }
-    }, async (input) => toolResult(await apiClient.post("/nodes/batch", input)));
+    }, async (input) => {
+        const result = await apiClient.post("/nodes/batch", input);
+        await autoAppendSearchFeedback();
+        return toolResult("recallx_create_nodes", result);
+    });
     registerTool(server, "recallx_create_relation", {
         title: "Create Relation",
         description: "Create a relation between two nodes. Agent-created relations typically start suggested and are promoted automatically when confidence improves.",
@@ -707,38 +1080,37 @@ export function createRecallXMcpServer(params) {
             source: sourceSchema,
             metadata: jsonRecordSchema
         }
-    }, createPostToolHandler(apiClient, "/relations"));
-    registerReadOnlyTool(server, "recallx_list_governance_issues", {
-        title: "List Governance Issues",
-        description: "List contested or low-confidence governance items that may need inspection.",
+    }, createPostToolHandler("recallx_create_relation", apiClient, "/relations"));
+    registerReadOnlyTool(server, "recallx_governance", {
+        title: "Governance",
+        description: "Read governance issues, check a specific entity's state, or trigger a recompute pass. **When to use:** after creating/editing content to verify it landed in good shape, or when reviewing items flagged as contested/low_confidence. Use action='issues' (default) to list problems, action='state' to inspect one entity, or action='recompute' to refresh state.",
         inputSchema: {
-            states: z.array(z.enum(governanceStates)).default(["contested", "low_confidence"]),
-            limit: z.number().int().min(1).max(100).default(20)
+            action: z.enum(["issues", "state", "recompute"]).default("issues"),
+            states: z.array(z.enum(governanceStates)).default(["contested", "low_confidence"]).describe("Issue states to include (for action='issues')."),
+            limit: z.number().int().min(1).max(100).default(20).describe("Max issues (for action='issues') or recompute batch (for action='recompute')."),
+            entityType: z.enum(["node", "relation"]).optional().describe("Required for action='state': entity type to inspect."),
+            entityId: z.string().min(1).optional().describe("Required for action='state': entity ID to inspect."),
+            entityIds: z.array(z.string().min(1)).max(200).optional().describe("Specific entity IDs to recompute (for action='recompute').")
+        }
+    }, async ({ action, states, limit, entityType, entityId, entityIds }) => {
+        if (action === "state") {
+            if (!entityType || !entityId) {
+                throw new Error("Invalid arguments for tool recallx_governance: action='state' requires entityType and entityId.");
+            }
+            return toolResult("recallx_governance", await apiClient.get(`/governance/state/${encodeURIComponent(entityType)}/${encodeURIComponent(entityId)}`));
+        }
+        if (action === "recompute") {
+            const body = { limit };
+            if (entityIds?.length)
+                body.entityIds = entityIds;
+            return toolResult("recallx_governance", await apiClient.post("/governance/recompute", body));
         }
-    }, async ({ states, limit }) => {
         const query = new URLSearchParams({
             states: states.join(","),
             limit: String(limit)
         });
-        return toolResult(await apiClient.get(`/governance/issues?${query.toString()}`));
+        return toolResult("recallx_governance", await apiClient.get(`/governance/issues?${query.toString()}`));
     });
-    registerReadOnlyTool(server, "recallx_get_governance_state", {
-        title: "Get Governance State",
-        description: "Read the current automatic governance state and recent events for a node or relation.",
-        inputSchema: {
-            entityType: z.enum(["node", "relation"]),
-            entityId: z.string().min(1)
-        }
-    }, async ({ entityType, entityId }) => toolResult(await apiClient.get(`/governance/state/${encodeURIComponent(entityType)}/${encodeURIComponent(entityId)}`)));
-    registerTool(server, "recallx_recompute_governance", {
-        title: "Recompute Governance",
-        description: "Run a bounded automatic governance recompute pass for nodes, relations, or both.",
-        inputSchema: {
-            entityType: z.enum(["node", "relation"]).optional(),
-            entityIds: z.array(z.string().min(1)).max(200).optional(),
-            limit: z.number().int().min(1).max(500).default(100)
-        }
-    }, createPostToolHandler(apiClient, "/governance/recompute"));
     registerReadOnlyTool(server, "recallx_context_bundle", {
         title: "Build Context Bundle",
         description: "Build a compact RecallX context bundle for coding, research, writing, or decision support. Omit targetId to get a workspace-entry bundle when the work is not yet tied to a specific project or node, and add targetId only after you know which project or node should anchor the context.",
@@ -766,30 +1138,35 @@ export function createRecallXMcpServer(params) {
                 maxItems: 10
             })
         }
-    }, async ({ targetId, ...input }) => toolResult(await apiClient.post("/context/bundles", {
-        ...input,
-        ...(targetId
-            ? {
-                target: {
-                    id: targetId
+    }, async ({ targetId, ...input }) => {
+        const result = await apiClient.post("/context/bundles", {
+            ...input,
+            ...(targetId
+                ? {
+                    target: {
+                        id: targetId
+                    }
                 }
-            }
-            : {})
-    })));
+                : {})
+        });
+        const items = Array.isArray(result.items) ? result.items : [];
+        const ids = items.filter((item) => isRecord(item) && typeof item.id === "string").map((item) => item.id);
+        sessionFeedback.trackBundle(targetId, ids);
+        return toolResult("recallx_context_bundle", result);
+    });
     registerTool(server, "recallx_semantic_reindex", {
-        title: "Queue Semantic Reindex",
-        description: "Queue semantic reindexing for a bounded set of recent active workspace nodes.",
+        title: "Semantic Reindex",
+        description: "Queue semantic reindexing for recent workspace nodes or a specific node. **When to use:** after editing node content that needs updated embeddings, or when semantic search results seem stale. Omit nodeId to reindex recent nodes.",
         inputSchema: {
-            limit: coerceIntegerSchema(250, 1, 1000)
+            nodeId: z.string().min(1).optional().describe("If provided, reindex only this specific node. Otherwise, reindex recent active nodes."),
+            limit: coerceIntegerSchema(250, 1, 1000).describe("Max nodes to reindex (ignored when nodeId is provided).")
         }
-    }, createPostToolHandler(apiClient, "/semantic/reindex"));
-    registerTool(server, "recallx_semantic_reindex_node", {
-        title: "Queue Node Semantic Reindex",
-        description: "Queue semantic reindexing for a specific node id.",
-        inputSchema: {
-            nodeId: z.string().min(1)
+    }, async ({ nodeId, limit }) => {
+        if (nodeId) {
+            return toolResult("recallx_semantic_reindex", await apiClient.post(`/semantic/reindex/${encodeURIComponent(nodeId)}`, {}));
         }
-    }, async ({ nodeId }) => toolResult(await apiClient.post(`/semantic/reindex/${encodeURIComponent(nodeId)}`, {})));
+        return toolResult("recallx_semantic_reindex", await apiClient.post("/semantic/reindex", { limit }));
+    });
     registerReadOnlyTool(server, "recallx_rank_candidates", {
         title: "Rank Candidate Nodes",
         description: "Rank a bounded set of candidate node ids for a target using RecallX request-time retrieval scoring.",
@@ -799,6 +1176,6 @@ export function createRecallXMcpServer(params) {
             preset: bundlePresetSchema("for-assistant"),
             targetNodeId: z.string().optional()
         }
-    }, createPostToolHandler(apiClient, "/retrieval/rank-candidates"));
+    }, createPostToolHandler("recallx_rank_candidates", apiClient, "/retrieval/rank-candidates"));
     return server;
 }