recallx-headless 1.0.7 → 1.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 jazpiper
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -154,8 +154,10 @@ recallx workspace open --root /Users/name/Documents/RecallX-Test
 - Default API base: `http://127.0.0.1:8787/api/v1`
 - `recallx serve` starts the local RecallX API in-process from the installed package
 - The CLI stays thin for day-to-day API operations and defers behavior to the HTTP API contract
+- MCP tool results keep `structuredContent` as the authoritative payload; when possible the text mirror is a compact deterministic summary rather than a pretty JSON dump
 - `--format json` is useful when scripting, while `--format markdown` is best for `context`
 - `workspace open` switches the active workspace in the running local RecallX service without restarting the server
 - `recallx-mcp` is the direct stdio MCP entrypoint from the npm package
+- MCP tool results keep `structuredContent` authoritative and may render `content.text` as a compact deterministic summary instead of a pretty JSON mirror
 - See the root [`README.md`](../../README.md) for source-run usage and install paths
 - See [`docs/mcp.md`](../../docs/mcp.md) for editor MCP wiring details

package/app/cli/src/format.js

@@ -206,8 +206,18 @@ export function renderTelemetrySummary(data) {
     `since: ${data?.since || ""}`,
     `logs: ${data?.logsPath || ""}`,
     `events: ${data?.totalEvents ?? 0}`,
+    `slow threshold: ${data?.slowRequestThresholdMs ?? ""}ms`,
   ];
 
+  const hot = Array.isArray(data?.hotOperations) ? data.hotOperations : [];
+  if (hot.length > 0) {
+    lines.push("");
+    lines.push("Hot operations:");
+    for (const item of hot.slice(0, 5)) {
+      lines.push(`- [${item.surface}] ${item.operation} p95=${item.p95DurationMs ?? ""}ms errors=${item.errorCount}/${item.count}`);
+    }
+  }
+
   const slow = Array.isArray(data?.slowOperations) ? data.slowOperations : [];
   if (slow.length > 0) {
     lines.push("");

package/app/mcp/index.js

@@ -45,7 +45,7 @@ async function resolveObservabilityState() {
             workspaceRoot: typeof workspace.rootPath === "string" ? workspace.rootPath : process.cwd(),
             workspaceName: typeof workspace.workspaceName === "string" ? workspace.workspaceName : "RecallX MCP",
             retentionDays: typeof values["observability.retentionDays"] === "number" ? values["observability.retentionDays"] : 14,
-            slowRequestMs: typeof values["observability.slowRequestMs"] === "number" ? values["observability.slowRequestMs"] : 250,
+            slowRequestMs: typeof values["observability.slowRequestMs"] === "number" ? values["observability.slowRequestMs"] : 50,
             capturePayloadShape: values["observability.capturePayloadShape"] !== false
         };
     }
@@ -55,7 +55,7 @@ async function resolveObservabilityState() {
             workspaceRoot: process.cwd(),
             workspaceName: "RecallX MCP",
             retentionDays: 14,
-            slowRequestMs: 250,
+            slowRequestMs: 50,
             capturePayloadShape: true
         };
     }

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;
@@ -335,7 +591,7 @@ export function createRecallXMcpServer(params) {
         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.",
         capabilities: {
             logging: {}
         }
@@ -388,12 +644,12 @@ export function createRecallXMcpServer(params) {
             includeDetails: z.boolean().optional().default(true)
         }),
         outputSchema: healthOutputSchema
-    }, async () => toolResult(await apiClient.get("/health")));
+    }, 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(apiClient, "/workspace"));
+    }, 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.",
@@ -401,7 +657,7 @@ export function createRecallXMcpServer(params) {
             current: workspaceInfoSchema,
             items: z.array(workspaceInfoSchema.extend({ isCurrent: z.boolean(), lastOpenedAt: z.string() }))
         })
-    }, createGetToolHandler(apiClient, "/workspaces"));
+    }, createGetToolHandler("recallx_workspace_list", apiClient, "/workspaces"));
     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,14 +665,14 @@ 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"));
+    }, 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.",
@@ -434,7 +690,7 @@ export function createRecallXMcpServer(params) {
                 failed: z.number()
             })
         })
-    }, createGetToolHandler(apiClient, "/semantic/status"));
+    }, 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.",
@@ -462,7 +718,7 @@ export function createRecallXMcpServer(params) {
         if (statuses?.length) {
             params.set("statuses", statuses.join(","));
         }
-        return toolResult(await apiClient.get(`/semantic/issues?${params.toString()}`));
+        return toolResult("recallx_semantic_issues", await apiClient.get(`/semantic/issues?${params.toString()}`));
     });
     registerReadOnlyTool(server, "recallx_search_nodes", {
         title: "Search Nodes",
@@ -486,7 +742,7 @@ export function createRecallXMcpServer(params) {
             offset: coerceIntegerSchema(0, 0, 10_000),
             sort: z.enum(["relevance", "updated_at"]).default("relevance")
         }
-    }, createNormalizedPostToolHandler(apiClient, "/nodes/search", normalizeNodeSearchInput));
+    }, createNormalizedPostToolHandler("recallx_search_nodes", apiClient, "/nodes/search", normalizeNodeSearchInput));
     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 +764,7 @@ export function createRecallXMcpServer(params) {
             offset: coerceIntegerSchema(0, 0, 10_000),
             sort: z.enum(["relevance", "updated_at"]).default("relevance")
         }
-    }, createNormalizedPostToolHandler(apiClient, "/activities/search", normalizeActivitySearchInput));
+    }, createNormalizedPostToolHandler("recallx_search_activities", apiClient, "/activities/search", normalizeActivitySearchInput));
     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 +794,14 @@ export function createRecallXMcpServer(params) {
             offset: coerceIntegerSchema(0, 0, 10_000),
             sort: z.enum(["relevance", "updated_at", "smart"]).default("relevance")
         }
-    }, createNormalizedPostToolHandler(apiClient, "/search", normalizeWorkspaceSearchInput));
+    }, createNormalizedPostToolHandler("recallx_search_workspace", apiClient, "/search", normalizeWorkspaceSearchInput));
     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,7 +821,7 @@ 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",
@@ -583,7 +839,7 @@ export function createRecallXMcpServer(params) {
             expiresAt: z.string().optional(),
             metadata: jsonRecordSchema
         }
-    }, createPostToolHandler(apiClient, "/inferred-relations"));
+    }, 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.",
@@ -597,7 +853,7 @@ export function createRecallXMcpServer(params) {
             delta: z.number(),
             metadata: jsonRecordSchema
         }
-    }, createPostToolHandler(apiClient, "/relation-usage-events"));
+    }, 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.",
@@ -612,7 +868,7 @@ export function createRecallXMcpServer(params) {
             confidence: z.number().min(0).max(1).default(1),
             metadata: jsonRecordSchema
         }
-    }, createPostToolHandler(apiClient, "/search-feedback-events"));
+    }, 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.",
@@ -621,7 +877,7 @@ export function createRecallXMcpServer(params) {
             generator: z.string().min(1).optional(),
             limit: z.number().int().min(1).max(500).default(100)
         }
-    }, createPostToolHandler(apiClient, "/inferred-relations/recompute"));
+    }, createPostToolHandler("recallx_recompute_inferred_relations", apiClient, "/inferred-relations/recompute"));
     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 +888,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 +902,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 +919,7 @@ export function createRecallXMcpServer(params) {
         }
     }, async (input) => {
         try {
-            return toolResult(await apiClient.post("/nodes", input));
+            return toolResult("recallx_create_node", await apiClient.post("/nodes", input));
         }
         catch (error) {
             if (error instanceof RecallXApiError &&
@@ -695,7 +951,7 @@ export function createRecallXMcpServer(params) {
                 .min(1)
                 .max(100)
         }
-    }, async (input) => toolResult(await apiClient.post("/nodes/batch", input)));
+    }, async (input) => toolResult("recallx_create_nodes", await apiClient.post("/nodes/batch", input)));
     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,7 +963,7 @@ export function createRecallXMcpServer(params) {
             source: sourceSchema,
             metadata: jsonRecordSchema
         }
-    }, createPostToolHandler(apiClient, "/relations"));
+    }, 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.",
@@ -720,7 +976,7 @@ export function createRecallXMcpServer(params) {
             states: states.join(","),
             limit: String(limit)
         });
-        return toolResult(await apiClient.get(`/governance/issues?${query.toString()}`));
+        return toolResult("recallx_list_governance_issues", await apiClient.get(`/governance/issues?${query.toString()}`));
     });
     registerReadOnlyTool(server, "recallx_get_governance_state", {
         title: "Get Governance State",
@@ -729,7 +985,7 @@ export function createRecallXMcpServer(params) {
             entityType: z.enum(["node", "relation"]),
             entityId: z.string().min(1)
         }
-    }, async ({ entityType, entityId }) => toolResult(await apiClient.get(`/governance/state/${encodeURIComponent(entityType)}/${encodeURIComponent(entityId)}`)));
+    }, 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.",
@@ -738,7 +994,7 @@ export function createRecallXMcpServer(params) {
             entityIds: z.array(z.string().min(1)).max(200).optional(),
             limit: z.number().int().min(1).max(500).default(100)
         }
-    }, createPostToolHandler(apiClient, "/governance/recompute"));
+    }, 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.",
@@ -766,7 +1022,7 @@ export function createRecallXMcpServer(params) {
                 maxItems: 10
             })
         }
-    }, async ({ targetId, ...input }) => toolResult(await apiClient.post("/context/bundles", {
+    }, async ({ targetId, ...input }) => toolResult("recallx_context_bundle", await apiClient.post("/context/bundles", {
         ...input,
         ...(targetId
             ? {
@@ -782,14 +1038,14 @@ export function createRecallXMcpServer(params) {
         inputSchema: {
             limit: coerceIntegerSchema(250, 1, 1000)
         }
-    }, createPostToolHandler(apiClient, "/semantic/reindex"));
+    }, 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 }) => toolResult(await apiClient.post(`/semantic/reindex/${encodeURIComponent(nodeId)}`, {})));
+    }, async ({ nodeId }) => toolResult("recallx_semantic_reindex_node", await apiClient.post(`/semantic/reindex/${encodeURIComponent(nodeId)}`, {})));
     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 +1055,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;
 }

package/app/server/app.js

@@ -9,7 +9,7 @@ import { AppError } from "./errors.js";
 import { isShortLogLikeAgentNodeInput, maybeCreatePromotionCandidate, recomputeAutomaticGovernance, resolveGovernancePolicy, resolveNodeGovernance, resolveRelationStatus, shouldPromoteActivitySummary } from "./governance.js";
 import { refreshAutomaticInferredRelationsForNode, reindexAutomaticInferredRelations } from "./inferred-relations.js";
 import { appendCurrentTelemetryDetails, createObservabilityWriter, summarizePayloadShape } from "./observability.js";
-import { buildSemanticCandidateBonusMap, buildCandidateRelationBonusMap, buildContextBundle, buildNeighborhoodItems, buildTargetRelatedRetrievalItems, bundleAsMarkdown, computeRankCandidateScore, shouldUseSemanticCandidateAugmentation } from "./retrieval.js";
+import { buildSemanticCandidateBonusMap, buildCandidateRelationBonusMap, buildContextBundle, buildNeighborhoodItems, buildNeighborhoodItemsBatch, buildTargetRelatedRetrievalItems, bundleAsMarkdown, computeRankCandidateScore, selectSemanticCandidateIds, shouldUseSemanticCandidateAugmentation } from "./retrieval.js";
 import { buildProjectGraph } from "./project-graph.js";
 import { createId, isPathWithinRoot } from "./utils.js";
 const relationTypeSet = new Set(relationTypes);
@@ -546,7 +546,7 @@ export function createRecallXApp(params) {
             workspaceRoot: currentWorkspaceRoot(),
             workspaceName: currentWorkspaceInfo().workspaceName,
             retentionDays: Math.max(1, parseNumberSetting(settings["observability.retentionDays"], 14)),
-            slowRequestMs: Math.max(1, parseNumberSetting(settings["observability.slowRequestMs"], 250)),
+            slowRequestMs: Math.max(1, parseNumberSetting(settings["observability.slowRequestMs"], 50)),
             capturePayloadShape: parseBooleanSetting(settings["observability.capturePayloadShape"], true)
         };
     };
@@ -1779,19 +1779,17 @@ export function createRecallXApp(params) {
         }, (span) => {
             const repository = currentRepository();
             const nodeId = readRequestParam(request.params.id);
-            const result = buildNeighborhoodItems(repository, nodeId, {
+            const neighborhoodOptions = {
                 relationTypes: types,
                 includeInferred,
                 maxInferred
-            });
+            };
+            const result = buildNeighborhoodItems(repository, nodeId, neighborhoodOptions);
             const expanded = depth === 2
                 ? (() => {
                     const seen = new Set(result.map((item) => `${item.edge.relationId}:${item.node.id}:1`));
-                    const secondHop = result.flatMap((item) => buildNeighborhoodItems(repository, item.node.id, {
-                        relationTypes: types,
-                        includeInferred,
-                        maxInferred
-                    })
+                    const secondHopByNodeId = buildNeighborhoodItemsBatch(repository, result.map((item) => item.node.id), neighborhoodOptions);
+                    const secondHop = result.flatMap((item) => (secondHopByNodeId.get(item.node.id) ?? [])
                         .filter((nested) => nested.node.id !== nodeId)
                         .map((nested) => ({
                         ...nested,
@@ -1814,7 +1812,8 @@ export function createRecallXApp(params) {
                 })()
                 : result;
             span.addDetails({
-                resultCount: expanded.length
+                resultCount: expanded.length,
+                firstHopCount: result.length
             });
             return expanded;
         });
@@ -2154,8 +2153,9 @@ export function createRecallXApp(params) {
             });
             const semanticAugmentation = repository.getSemanticAugmentationSettings();
             const semanticEnabled = shouldUseSemanticCandidateAugmentation(query, candidates);
+            const semanticCandidateIds = selectSemanticCandidateIds(query, candidates);
             const semanticBonuses = semanticEnabled
-                ? buildSemanticCandidateBonusMap(await repository.rankSemanticCandidates(query, candidateNodeIds), semanticAugmentation)
+                ? buildSemanticCandidateBonusMap(await repository.rankSemanticCandidates(query, semanticCandidateIds), semanticAugmentation)
                 : new Map();
             const result = candidates
                 .map((node) => {
@@ -2179,7 +2179,9 @@ export function createRecallXApp(params) {
                 .sort((left, right) => right.score - left.score);
             span.addDetails({
                 resultCount: result.length,
-                semanticUsed: semanticEnabled
+                semanticUsed: semanticEnabled,
+                semanticCandidateCount: candidates.length,
+                semanticRankedCandidateCount: semanticCandidateIds.length
             });
             return result;
         });

package/app/server/inferred-relations.js

@@ -14,6 +14,9 @@ function normalizeText(value) {
 function normalizeTags(tags) {
     return Array.from(new Set(tags.map((tag) => normalizeText(tag)).filter(Boolean)));
 }
+function normalizeTexts(values) {
+    return values.map(normalizeText).filter(Boolean);
+}
 function escapeRegExp(value) {
     return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
 }
@@ -33,6 +36,10 @@ function mentionsNode(haystacks, candidate) {
         : false;
     return { idMention, titleMention };
 }
+function hasCheapMention(normalizedHaystacks, candidate) {
+    const normalizedTitle = normalizeText(candidate.title);
+    return normalizedHaystacks.some((haystack) => haystack.includes(candidate.id.toLowerCase()) || (normalizedTitle.length >= 5 && haystack.includes(normalizedTitle)));
+}
 function sortPair(left, right) {
     return left.localeCompare(right) <= 0 ? [left, right] : [right, left];
 }
@@ -154,36 +161,42 @@ function collectGeneratedCandidates(repository, target, trigger) {
         projectIds: new Set(projectMembershipsByNodeId.get(target.id) ?? []),
         artifactKeys: artifactKeysByNodeId.get(target.id) ?? { exactPaths: [], baseNames: [] }
     };
+    const normalizedTargetTexts = normalizeTexts([target.title, target.body, target.summary]);
     const activityBodies = trigger === "activity-append" || trigger === "reindex"
         ? repository
             .listNodeActivities(target.id, MAX_ACTIVITY_BODIES)
             .map((activity) => activity.body ?? "")
             .filter(Boolean)
         : [];
+    const normalizedActivityBodies = activityBodies.map(normalizeText).filter(Boolean);
     return candidates.flatMap((candidate) => {
         const generated = [];
+        const candidateProjectIds = projectMembershipsByNodeId.get(candidate.id) ?? [];
+        const candidateArtifacts = artifactKeysByNodeId.get(candidate.id) ?? { exactPaths: [], baseNames: [] };
         const tagOverlapCandidate = buildTagOverlapCandidate(target, candidate, targetContext.normalizedTags);
         if (tagOverlapCandidate) {
             generated.push(tagOverlapCandidate);
         }
-        const bodyReferenceCandidate = buildBodyReferenceCandidate(target, candidate);
+        const projectMembershipCandidate = buildProjectMembershipCandidate(target, candidate, candidateProjectIds, targetContext.projectIds);
+        if (projectMembershipCandidate) {
+            generated.push(projectMembershipCandidate);
+        }
+        const sharedArtifactCandidate = buildSharedArtifactCandidate(target, candidate, candidateArtifacts, targetContext.artifactKeys);
+        if (sharedArtifactCandidate) {
+            generated.push(sharedArtifactCandidate);
+        }
+        const candidateTexts = normalizeTexts([candidate.title, candidate.body, candidate.summary]);
+        const shouldCheckBodyReference = hasCheapMention(normalizedTargetTexts, candidate) || hasCheapMention(candidateTexts, target);
+        const bodyReferenceCandidate = shouldCheckBodyReference ? buildBodyReferenceCandidate(target, candidate) : null;
         if (bodyReferenceCandidate) {
             generated.push(bodyReferenceCandidate);
         }
-        if (activityBodies.length) {
+        if (normalizedActivityBodies.length && hasCheapMention(normalizedActivityBodies, candidate)) {
             const activityReferenceCandidate = buildActivityReferenceCandidate(target, candidate, activityBodies);
             if (activityReferenceCandidate) {
                 generated.push(activityReferenceCandidate);
             }
         }
-        const projectMembershipCandidate = buildProjectMembershipCandidate(target, candidate, projectMembershipsByNodeId.get(candidate.id) ?? [], targetContext.projectIds);
-        if (projectMembershipCandidate) {
-            generated.push(projectMembershipCandidate);
-        }
-        const sharedArtifactCandidate = buildSharedArtifactCandidate(target, candidate, artifactKeysByNodeId.get(candidate.id) ?? { exactPaths: [], baseNames: [] }, targetContext.artifactKeys);
-        if (sharedArtifactCandidate) {
-            generated.push(sharedArtifactCandidate);
-        }
         return generated;
     });
 }

package/app/server/observability.js

@@ -1,6 +1,8 @@
 import { AsyncLocalStorage } from "node:async_hooks";
-import { appendFile, mkdir, readFile, readdir, unlink } from "node:fs/promises";
+import { createReadStream } from "node:fs";
+import { appendFile, mkdir, readdir, unlink } from "node:fs/promises";
 import path from "node:path";
+import { createInterface } from "node:readline";
 import { createId } from "./utils.js";
 const telemetryStorage = new AsyncLocalStorage();
 function nowIso() {
@@ -45,6 +47,10 @@ function roundDuration(value) {
 function dateStamp(value) {
     return value.slice(0, 10);
 }
+function telemetryLogDate(entry) {
+    const match = /^telemetry-(\d{4}-\d{2}-\d{2})\.ndjson$/.exec(entry);
+    return match ? match[1] : null;
+}
 function normalizeRetentionDays(value) {
     return Math.max(1, Math.trunc(value || 14));
 }
@@ -341,24 +347,41 @@ export class ObservabilityWriter {
         }
         const files = entries
             .filter((entry) => /^telemetry-\d{4}-\d{2}-\d{2}\.ndjson$/.test(entry))
+            .filter((entry) => {
+            const stamp = telemetryLogDate(entry);
+            return stamp !== null && stamp >= dateStamp(new Date(sinceMs).toISOString());
+        })
             .sort();
         const events = [];
         for (const file of files) {
             const filePath = path.join(logsDir, file);
-            const content = await readFile(filePath, "utf8").catch(() => "");
-            for (const line of content.split("\n")) {
-                const event = parseJsonLine(line);
-                if (!event) {
-                    continue;
-                }
-                const eventMs = Date.parse(event.ts);
-                if (!Number.isFinite(eventMs) || eventMs < sinceMs) {
-                    continue;
-                }
-                if (options.surface && options.surface !== "all" && event.surface !== options.surface) {
-                    continue;
+            const stream = createReadStream(filePath, { encoding: "utf8" });
+            const lines = createInterface({
+                input: stream,
+                crlfDelay: Number.POSITIVE_INFINITY
+            });
+            try {
+                for await (const line of lines) {
+                    const event = parseJsonLine(line);
+                    if (!event) {
+                        continue;
+                    }
+                    const eventMs = Date.parse(event.ts);
+                    if (!Number.isFinite(eventMs) || eventMs < sinceMs) {
+                        continue;
+                    }
+                    if (options.surface && options.surface !== "all" && event.surface !== options.surface) {
+                        continue;
+                    }
+                    events.push(event);
                 }
-                events.push(event);
+            }
+            catch {
+                // Ignore individual file read failures so observability endpoints stay resilient.
+            }
+            finally {
+                lines.close();
+                stream.destroy();
             }
         }
         return {
@@ -724,7 +747,9 @@ export class ObservabilityWriter {
             generatedAt: nowIso(),
             logsPath,
             totalEvents: events.length,
+            slowRequestThresholdMs: state.slowRequestMs,
             operationSummaries,
+            hotOperations: operationSummaries.slice(0, 10),
             slowOperations: operationSummaries
                 .filter((item) => (item.p95DurationMs ?? 0) >= state.slowRequestMs)
                 .slice(0, 10),

package/app/server/repositories.js

@@ -59,12 +59,14 @@ function collectSearchFieldSignals(matcher, candidates) {
             matchedFields: [],
             exactFields: [],
             matchedTermCount: 0,
+            matchedTermCounts: {},
             totalTermCount: 0
         };
     }
     const matchedFields = new Set();
     const exactFields = new Set();
     const matchedTerms = new Set();
+    const matchedTermCounts = {};
     for (const candidate of candidates) {
         const haystack = normalizeSearchText(candidate.value);
         if (!haystack) {
@@ -76,6 +78,7 @@ function collectSearchFieldSignals(matcher, candidates) {
             continue;
         }
         matchedFields.add(candidate.field);
+        matchedTermCounts[candidate.field] = termMatches.length;
         if (exactMatch) {
             exactFields.add(candidate.field);
         }
@@ -87,6 +90,7 @@ function collectSearchFieldSignals(matcher, candidates) {
         matchedFields: [...matchedFields],
         exactFields: [...exactFields],
         matchedTermCount: matchedTerms.size,
+        matchedTermCounts,
         totalTermCount: matcher.matchTerms.length
     };
 }
@@ -94,14 +98,18 @@ function classifyNodeLexicalQuality(strategy, signals) {
     if (strategy === "browse" || strategy === "semantic" || !signals.matchedFields.length) {
         return "none";
     }
-    if (strategy === "fallback_token") {
-        return "weak";
-    }
-    const strongExactFields = new Set(["title", "summary", "tags"]);
+    const strongExactFields = new Set(["title", "summary", "tags", "body"]);
     if (signals.exactFields.some((field) => strongExactFields.has(field))) {
         return "strong";
     }
     const termCoverage = signals.totalTermCount > 0 ? signals.matchedTermCount / signals.totalTermCount : 0;
+    const titleCoverage = signals.totalTermCount > 0 ? (signals.matchedTermCounts.title ?? 0) / signals.totalTermCount : 0;
+    if (strategy === "fallback_token") {
+        return titleCoverage >= 0.5 ? "strong" : "weak";
+    }
+    if (strategy === "fts" && titleCoverage >= 0.5) {
+        return "strong";
+    }
     if (strategy === "fts" && termCoverage >= 0.6 && signals.matchedFields.some((field) => strongExactFields.has(field))) {
         return "strong";
     }
@@ -2312,25 +2320,59 @@ export class RecallXRepository {
             : "";
         const rows = this.db
             .prepare(`SELECT
-           r.*,
-           CASE WHEN r.from_node_id = ? THEN r.to_node_id ELSE r.from_node_id END AS related_id
+           r.id,
+           r.from_node_id,
+           r.to_node_id,
+           r.relation_type,
+           r.status,
+           r.created_by,
+           r.source_type,
+           r.source_label,
+           r.created_at,
+           r.metadata_json,
+           n.id AS node_id,
+           n.type AS node_type,
+           n.status AS node_status,
+           n.canonicality AS node_canonicality,
+           n.visibility AS node_visibility,
+           n.title AS node_title,
+           n.body AS node_body,
+           n.summary AS node_summary,
+           n.created_by AS node_created_by,
+           n.source_type AS node_source_type,
+           n.source_label AS node_source_label,
+           n.created_at AS node_created_at,
+           n.updated_at AS node_updated_at,
+           n.tags_json AS node_tags_json,
+           n.metadata_json AS node_metadata_json
          FROM relations r
+         JOIN nodes n
+           ON n.id = CASE WHEN r.from_node_id = ? THEN r.to_node_id ELSE r.from_node_id END
          WHERE (r.from_node_id = ? OR r.to_node_id = ?)
            AND r.status != 'archived'
            ${relationWhere}
          ORDER BY r.created_at DESC`)
             .all(nodeId, nodeId, nodeId, ...(relationFilter ?? []));
-        const relatedNodes = this.getNodesByIds(rows.map((row) => String(row.related_id)));
-        return rows.flatMap((row) => {
-            const node = relatedNodes.get(String(row.related_id));
-            if (!node) {
-                return [];
+        return rows.map((row) => ({
+            relation: mapRelation(row),
+            node: {
+                id: String(row.node_id),
+                type: row.node_type,
+                status: row.node_status,
+                canonicality: row.node_canonicality,
+                visibility: String(row.node_visibility),
+                title: row.node_title ? String(row.node_title) : null,
+                body: row.node_body ? String(row.node_body) : null,
+                summary: row.node_summary ? String(row.node_summary) : null,
+                createdBy: row.node_created_by ? String(row.node_created_by) : null,
+                sourceType: row.node_source_type ? String(row.node_source_type) : null,
+                sourceLabel: row.node_source_label ? String(row.node_source_label) : null,
+                createdAt: String(row.node_created_at),
+                updatedAt: String(row.node_updated_at),
+                tags: parseJson(row.node_tags_json, []),
+                metadata: parseJson(row.node_metadata_json, {})
             }
-            return [{
-                    relation: mapRelation(row),
-                    node
-                }];
-        });
+        }));
     }
     listProjectMemberNodes(projectId, limit) {
         const rows = this.db

package/app/server/retrieval.js

@@ -18,6 +18,7 @@ const boostedRelationRankWeights = {
 };
 const semanticCandidateMinSimilarity = 0.2;
 const semanticCandidateMaxBonus = 18;
+const maxSemanticPrefilterCandidates = 256;
 function resolveSemanticAugmentationSettings(settings) {
     return {
         minSimilarity: typeof settings?.minSimilarity === "number" && Number.isFinite(settings.minSimilarity)
@@ -38,7 +39,15 @@ function prioritizeItems(items, preset, maxItems, bonuses) {
         .map(({ item }) => item);
     return weighted.slice(0, maxItems);
 }
-function buildNeighborhoodResult(repository, nodeId, options) {
+function normalizeRetrievalText(value) {
+    return (value ?? "").toLowerCase().replace(/\s+/g, " ").trim();
+}
+function tokenizeRetrievalText(value) {
+    return normalizeRetrievalText(value)
+        .split(/[^a-z0-9]+/g)
+        .filter((token) => token.length >= 3);
+}
+function listNeighborhoodCandidates(repository, nodeId, options) {
     const canonicalItems = repository.listRelatedNodes(nodeId, 1, options?.relationTypes).map(({ node, relation }) => ({
         node,
         edge: {
@@ -94,6 +103,13 @@ function buildNeighborhoodResult(repository, nodeId, options) {
             });
         })()
         : [];
+    return {
+        canonicalItems,
+        inferredItems
+    };
+}
+function buildNeighborhoodResult(repository, nodeId, options) {
+    const { canonicalItems, inferredItems } = listNeighborhoodCandidates(repository, nodeId, options);
     const usageSummaries = repository.getRelationUsageSummaries([...canonicalItems, ...inferredItems].map((item) => item.edge.relationId));
     const rankedCanonical = rankNeighborhoodItems(canonicalItems, usageSummaries, neighborhoodRetrievalRankWeights);
     const rankedInferred = options?.includeInferred && options.maxInferred
@@ -104,6 +120,27 @@ function buildNeighborhoodResult(repository, nodeId, options) {
         usageSummaries
     };
 }
+export function buildNeighborhoodItemsBatch(repository, nodeIds, options) {
+    const uniqueNodeIds = Array.from(new Set(nodeIds.filter(Boolean)));
+    const rawByNodeId = new Map();
+    const relationIds = [];
+    for (const nodeId of uniqueNodeIds) {
+        const raw = listNeighborhoodCandidates(repository, nodeId, options);
+        rawByNodeId.set(nodeId, raw);
+        relationIds.push(...raw.canonicalItems.map((item) => item.edge.relationId));
+        relationIds.push(...raw.inferredItems.map((item) => item.edge.relationId));
+    }
+    const usageSummaries = repository.getRelationUsageSummaries(relationIds);
+    const results = new Map();
+    for (const [nodeId, raw] of rawByNodeId.entries()) {
+        const rankedCanonical = rankNeighborhoodItems(raw.canonicalItems, usageSummaries, neighborhoodRetrievalRankWeights);
+        const rankedInferred = options?.includeInferred && options.maxInferred
+            ? rankNeighborhoodItems(raw.inferredItems, usageSummaries, neighborhoodRetrievalRankWeights, options.maxInferred)
+            : [];
+        results.set(nodeId, [...rankedCanonical, ...rankedInferred]);
+    }
+    return results;
+}
 function matchesSearchResultFilters(item, filters) {
     const typeMatches = !filters.types?.length || filters.types.includes(item.type);
     const statusMatches = !filters.status?.length || filters.status.includes(item.status);
@@ -214,6 +251,45 @@ export function buildSemanticCandidateBonusMap(semanticMatches, settings) {
         ];
     }));
 }
+function scoreSemanticPrefilterCandidate(normalizedQuery, queryTokens, candidate) {
+    const normalizedTitle = normalizeRetrievalText(candidate.title);
+    const normalizedSummary = normalizeRetrievalText(candidate.summary);
+    let score = 0;
+    if (normalizedTitle.includes(normalizedQuery)) {
+        score += 12;
+    }
+    if (normalizedSummary.includes(normalizedQuery)) {
+        score += 6;
+    }
+    for (const token of queryTokens) {
+        if (normalizedTitle.includes(token)) {
+            score += 2;
+        }
+        if (normalizedSummary.includes(token)) {
+            score += 1;
+        }
+    }
+    return score;
+}
+export function selectSemanticCandidateIds(query, candidates, maxCandidates = maxSemanticPrefilterCandidates) {
+    if (candidates.length <= maxCandidates) {
+        return candidates.map((candidate) => candidate.id);
+    }
+    const normalizedQuery = normalizeRetrievalText(query);
+    if (!normalizedQuery) {
+        return candidates.slice(0, maxCandidates).map((candidate) => candidate.id);
+    }
+    const queryTokens = Array.from(new Set(tokenizeRetrievalText(query)));
+    return candidates
+        .map((candidate) => ({
+        id: candidate.id,
+        score: scoreSemanticPrefilterCandidate(normalizedQuery, queryTokens, candidate),
+        updatedAt: candidate.updatedAt
+    }))
+        .sort((left, right) => right.score - left.score || right.updatedAt.localeCompare(left.updatedAt))
+        .slice(0, maxCandidates)
+        .map((candidate) => candidate.id);
+}
 function computeBundleRelationBoost(item, summary) {
     return computeRelationRetrievalRank(item.edge, summary, {
         canonicalBase: 120,
@@ -397,15 +473,19 @@ export async function buildContextBundle(repository, input) {
     const candidateItems = [targetItem, ...relatedItems, ...decisions, ...openQuestions];
     const dedupedItems = Array.from(new Map(candidateItems.map((item) => [item.id, item])).values());
     const semanticQuery = [target.title, target.summary ?? target.body].filter(Boolean).join("\n");
-    const semanticBonuses = shouldUseSemanticCandidateAugmentation(semanticQuery, dedupedItems.filter((item) => item.id !== target.id))
-        ? buildSemanticCandidateBonusMap(await repository.rankSemanticCandidates(semanticQuery, dedupedItems.filter((item) => item.id !== target.id).map((item) => item.id)), repository.getSemanticAugmentationSettings())
+    const semanticCandidates = dedupedItems.filter((item) => item.id !== target.id);
+    const semanticCandidateIds = selectSemanticCandidateIds(semanticQuery, semanticCandidates);
+    const semanticBonuses = shouldUseSemanticCandidateAugmentation(semanticQuery, semanticCandidates)
+        ? buildSemanticCandidateBonusMap(await repository.rankSemanticCandidates(semanticQuery, semanticCandidateIds), repository.getSemanticAugmentationSettings())
         : new Map();
     appendCurrentTelemetryDetails({
         neighborhoodCount: neighborhood.length,
         relatedCandidateCount: relatedItems.length,
         decisionCount: decisions.length,
         openQuestionCount: openQuestions.length,
-        semanticUsed: semanticBonuses.size > 0
+        semanticUsed: semanticBonuses.size > 0,
+        semanticCandidateCount: semanticCandidates.length,
+        semanticRankedCandidateCount: semanticCandidateIds.length
     });
     const combinedBonuses = new Map();
     for (const item of dedupedItems) {

package/app/server/workspace-session.js

@@ -98,7 +98,7 @@ export class WorkspaceSessionManager {
             "relations.autoRecompute.lastRunAt": null,
             "observability.enabled": false,
             "observability.retentionDays": 14,
-            "observability.slowRequestMs": 250,
+            "observability.slowRequestMs": 50,
             "observability.capturePayloadShape": true,
             "export.defaultFormat": "markdown",
         });

package/app/shared/version.js

@@ -1 +1 @@
-export const RECALLX_VERSION = "1.0.7";
+export const RECALLX_VERSION = "1.1.0";

package/package.json

@@ -1,8 +1,13 @@
 {
   "name": "recallx-headless",
-  "version": "1.0.7",
+  "version": "1.1.0",
   "description": "Headless RecallX runtime with API, CLI, and MCP entrypoint.",
   "type": "module",
+  "author": {
+    "name": "jazpiper",
+    "email": "jazpiper1@gmail.com"
+  },
+  "license": "MIT",
   "bin": {
     "recallx": "./app/cli/bin/recallx.js",
     "recallx-mcp": "./app/cli/bin/recallx-mcp.js"
@@ -12,7 +17,8 @@
     "app/mcp",
     "app/shared",
     "app/server",
-    "README.md"
+    "README.md",
+    "LICENSE"
   ],
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.27.1",