recallx-headless 1.1.0 → 1.2.0

package/app/cli/src/cli.js

@@ -6,7 +6,7 @@ import { fileURLToPath, pathToFileURL } from "node:url";
 import { getApiBase, getAuthToken, requestJson } from "./http.js";
 import { RECALLX_VERSION } from "../../shared/version.js";
 import { applyCliUpdate, getCliUpdatePlan } from "./update.js";
-import { renderActivitySearchResults, renderBundleMarkdown, renderGovernanceIssues, renderJson, renderNode, renderRelated, renderSearchResults, renderTelemetryErrors, renderTelemetrySummary, renderText, renderUpdateResult, renderWorkspaceSearchResults, renderWorkspaces, } from "./format.js";
+import { renderActivitySearchResults, renderBundleMarkdown, renderGovernanceIssues, renderJson, renderNode, renderRelated, renderSearchResults, renderTelemetryErrors, renderTelemetrySummary, renderText, renderUpdateResult, renderWorkspaceBackups, renderWorkspaceSearchResults, renderWorkspaces, } from "./format.js";
 const DEFAULT_SOURCE = {
     actorType: "human",
     actorLabel: "recallx-cli",
@@ -465,6 +465,27 @@ async function runWorkspace(apiBase, token, format, args, positionals) {
                 action,
                 rootPath: args.root || args.path || positionals[1],
             });
+        case "backups": {
+            const data = await requestJson(apiBase, "/workspaces/backups", { token });
+            outputData(data, format, "workspace-backups");
+            return;
+        }
+        case "backup":
+            return runPostCommand(apiBase, token, format, "/workspaces/backups", "workspace-backup", {
+                label: args.label || args.name || positionals[1],
+            });
+        case "export":
+            return runPostCommand(apiBase, token, format, "/workspaces/export", "workspace-export", {
+                format: args.format || args.kind || "json",
+            });
+        case "restore":
+            validateRequired(args.backup || args.id || positionals[1], "workspace restore requires --backup");
+            validateRequired(args.root || args.path || positionals[2], "workspace restore requires --root");
+            return runPostCommand(apiBase, token, format, "/workspaces/restore", "workspace-restore", {
+                backupId: args.backup || args.id || positionals[1],
+                targetRootPath: args.root || args.path || positionals[2],
+                workspaceName: args.name || args.title,
+            });
     }
     throw new Error(`Unknown workspace action: ${action}`);
 }
@@ -547,6 +568,9 @@ function outputData(data, format, command) {
         case "workspace-list":
             writeStdout(renderWorkspaces(payload));
             return;
+        case "workspace-backups":
+            writeStdout(renderWorkspaceBackups(payload));
+            return;
         case "append":
         case "create":
         case "link":
@@ -557,6 +581,9 @@ function outputData(data, format, command) {
         case "workspace-current":
         case "workspace-create":
         case "workspace-open":
+        case "workspace-backup":
+        case "workspace-export":
+        case "workspace-restore":
             writeStdout(renderText(payload));
             return;
         case "observability-summary":
@@ -696,6 +723,10 @@ Usage:
   recallx workspace list
   recallx workspace create --root /path/to/workspace [--name "Personal"]
   recallx workspace open --root /path/to/workspace
+  recallx workspace backups
+  recallx workspace backup [--label "before-upgrade"]
+  recallx workspace export [--format json|markdown]
+  recallx workspace restore --backup <id> --root /path/to/restore [--name "Recovered"]
   recallx observability summary [--since 24h]
   recallx observability errors [--since 24h] [--surface mcp] [--limit 50]
 

package/app/cli/src/format.js

@@ -144,6 +144,20 @@ export function renderWorkspaces(data) {
     .join("\n\n")}\n`;
 }
 
+export function renderWorkspaceBackups(data) {
+  const items = data?.items || [];
+  if (!items.length) {
+    return "No backups.\n";
+  }
+
+  return `${items
+    .map(
+      (item, index) =>
+        `${index + 1}. ${item.label || item.id}\n  id: ${item.id}\n  created: ${item.createdAt}\n  path: ${item.backupPath}`,
+    )
+    .join("\n\n")}\n`;
+}
+
 export function renderUpdateResult(data) {
   const lines = [
     `package: ${data?.packageName || ""}`,

package/app/mcp/server.js

@@ -587,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 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.",
+        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: {}
         }
@@ -645,19 +689,25 @@ export function createRecallXMcpServer(params) {
         }),
         outputSchema: healthOutputSchema
     }, async () => toolResult("recallx_health", 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("recallx_workspace_current", apiClient, "/workspace"));
-    registerReadOnlyTool(server, "recallx_workspace_list", {
-        title: "List Workspaces",
-        description: "List known RecallX workspaces and identify the currently active one.",
+    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("recallx_workspace_list", 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.",
@@ -673,9 +723,14 @@ export function createRecallXMcpServer(params) {
             rootPath: z.string().min(1).describe("Existing workspace root path to open.")
         }
     }, createPostToolHandler("recallx_workspace_open", 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.",
+    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(),
@@ -688,37 +743,30 @@ export function createRecallXMcpServer(params) {
                 stale: z.number(),
                 ready: z.number(),
                 failed: z.number()
-            })
-        })
-    }, createGetToolHandler("recallx_semantic_status", 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("recallx_semantic_issues", await apiClient.get(`/semantic/issues?${params.toString()}`));
+        return toolResult("recallx_semantic_overview", result);
     });
     registerReadOnlyTool(server, "recallx_search_nodes", {
         title: "Search Nodes",
@@ -742,7 +790,14 @@ export function createRecallXMcpServer(params) {
             offset: coerceIntegerSchema(0, 0, 10_000),
             sort: z.enum(["relevance", "updated_at"]).default("relevance")
         }
-    }, createNormalizedPostToolHandler("recallx_search_nodes", 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.",
@@ -764,7 +819,14 @@ export function createRecallXMcpServer(params) {
             offset: coerceIntegerSchema(0, 0, 10_000),
             sort: z.enum(["relevance", "updated_at"]).default("relevance")
         }
-    }, createNormalizedPostToolHandler("recallx_search_activities", 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\"`.",
@@ -794,7 +856,15 @@ export function createRecallXMcpServer(params) {
             offset: coerceIntegerSchema(0, 0, 10_000),
             sort: z.enum(["relevance", "updated_at", "smart"]).default("relevance")
         }
-    }, createNormalizedPostToolHandler("recallx_search_workspace", 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.",
@@ -823,61 +893,102 @@ export function createRecallXMcpServer(params) {
         }
         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("recallx_upsert_inferred_relation", 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("recallx_append_relation_usage_event", 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("recallx_append_search_feedback", 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
+            }));
+        }
+        if (!input.relationId || !input.relationSource || !input.relationEventType) {
+            throw new Error("Invalid arguments for tool recallx_append_feedback: feedbackType='relation' requires relationId, relationSource, and relationEventType.");
         }
-    }, createPostToolHandler("recallx_recompute_inferred_relations", apiClient, "/inferred-relations/recompute"));
+        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.",
@@ -919,7 +1030,9 @@ export function createRecallXMcpServer(params) {
         }
     }, async (input) => {
         try {
-            return toolResult("recallx_create_node", 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 &&
@@ -951,7 +1064,11 @@ export function createRecallXMcpServer(params) {
                 .min(1)
                 .max(100)
         }
-    }, async (input) => toolResult("recallx_create_nodes", 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.",
@@ -964,37 +1081,36 @@ export function createRecallXMcpServer(params) {
             metadata: jsonRecordSchema
         }
     }, createPostToolHandler("recallx_create_relation", apiClient, "/relations"));
-    registerReadOnlyTool(server, "recallx_list_governance_issues", {
-        title: "List Governance Issues",
-        description: "List contested or low-confidence governance items that may need inspection.",
+    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("recallx_list_governance_issues", 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("recallx_get_governance_state", 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("recallx_recompute_governance", 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.",
@@ -1022,30 +1138,35 @@ export function createRecallXMcpServer(params) {
                 maxItems: 10
             })
         }
-    }, async ({ targetId, ...input }) => toolResult("recallx_context_bundle", 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("recallx_semantic_reindex", 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("recallx_semantic_reindex_node", 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.",