nlm-memory 0.20.0 → 0.21.0

package/dist/mcp/server.js

@@ -15,8 +15,22 @@ import { z } from "zod";
 import { logQuery } from "../core/recall/query-log.js";
 import { logFactQuery } from "../core/recall-facts/fact-query-log.js";
 import { appendCitation } from "../core/recall/citation-log.js";
+import { resolveConversationForSession } from "../core/hook/memo.js";
+import { resolveConversationByQuery } from "../core/hook/resolve-conversation-by-query.js";
 import { appendFactSupersedence, appendSupersedence, readSupersedenceLog } from "../core/storage/supersedence-log.js";
 import { recallCode } from "../core/exemplars/recall-code.js";
+import { buildWorkDigest } from "../core/work-digest/build-work-digest.js";
+import { composeWorkDigest } from "../core/work-digest/compose-work-digest.js";
+import { rollupWorkstream } from "../core/workstream/rollup.js";
+import { composeWorkstreamRecall } from "../core/workstream/compose-recall.js";
+import { normalizeLabel } from "../core/workstream/model.js";
+import { resolveWorkstreamId } from "../core/workstream/resolve.js";
+import { suggestMerges } from "../core/workstream/merge-suggest.js";
+import { normalizeSignal } from "../core/signals/ingest-signal.js";
+import { stampSignalScope } from "../core/signals/stamp-scope.js";
+import { deriveOutcome } from "../core/outcome/rollup.js";
+import { buildSqliteOutcomeDeps } from "../core/storage/sqlite-outcome-store.js";
+import { SIGNAL_OUTCOMES } from "../shared/types.js";
 const CHARACTER_LIMIT = 25_000;
 const DEFAULT_LIMIT = 10;
 const SERVER_NAME = "nlm-memory-mcp-server";
@@ -47,6 +61,9 @@ function truncate(data) {
 function ok(data) {
     return { content: [{ type: "text", text: truncate(data) }] };
 }
+function okText(text) {
+    return { content: [{ type: "text", text }] };
+}
 function err(error) {
     const message = error instanceof Error ? error.message : String(error);
     return {
@@ -63,12 +80,23 @@ function mcpRewriteDefault() {
         return true;
     return raw !== "0" && raw.toLowerCase() !== "false";
 }
-export async function recallSessionsHandler(deps, input) {
+/**
+ * Normalize an MCP client's self-reported identity (from the initialize
+ * handshake's clientInfo) into a runtime attribution string for the recall
+ * query-log. Returns null when no usable name is present, so the log stays
+ * honest about unknown callers. Trim + lowercase keeps aggregation clean
+ * (claude-code, cursor, hermes) and matches the hook-side runtime convention.
+ */
+export function mcpRuntimeFromClient(client) {
+    const name = client?.name?.trim().toLowerCase();
+    return name ? name : null;
+}
+export async function recallSessionsHandler(deps, input, runtime = null) {
     try {
         const rewrite = input.rewrite ?? mcpRewriteDefault();
         const query = {
             query: input.query ?? "",
-            mode: input.mode ?? "hybrid",
+            mode: input.mode ?? "keyword",
             limit: input.limit ?? DEFAULT_LIMIT,
             rewrite,
             // Investigative surface: include superseded sessions, down-ranked and
@@ -77,21 +105,24 @@ export async function recallSessionsHandler(deps, input) {
             includeSuperseded: true,
             ...(input.entity !== undefined ? { entity: input.entity } : {}),
             ...(input.kind !== undefined ? { kind: input.kind } : {}),
+            ...(input.workstream !== undefined ? { workstream: input.workstream } : {}),
         };
         const result = await deps.recall.search(query);
+        const conversationId = resolveConversationByQuery(input.query ?? "") ?? undefined;
         // Telemetry — the MCP path is the real agent-usage path; without this it
         // is invisible to query_log.jsonl and the Recall page. Fire-and-forget,
         // mirrors the HTTP /api/recall handler.
         void logQuery({
             source: "mcp",
-            runtime: null,
+            runtime,
             query: input.query ?? null,
             entity: input.entity ?? null,
             kind: input.kind ?? null,
-            mode: input.mode ?? "hybrid",
+            mode: input.mode ?? "keyword",
             limit: input.limit ?? DEFAULT_LIMIT,
             nResults: result.total,
             returnedIds: result.results.map((r) => r.id),
+            ...(conversationId !== undefined ? { conversationId } : {}),
         });
         return ok(result);
     }
@@ -99,6 +130,151 @@ export async function recallSessionsHandler(deps, input) {
         return err(e);
     }
 }
+export async function workSummaryHandler(deps, input) {
+    if (!deps.workDigest) {
+        return okText("work_summary is not available in this deployment.");
+    }
+    try {
+        const date = input.date ?? localToday();
+        const digest = await buildWorkDigest(deps.workDigest, date);
+        return okText(composeWorkDigest(digest));
+    }
+    catch (e) {
+        return err(e);
+    }
+}
+export async function recallWorkstreamHandler(deps, input, runtime = null) {
+    if (!deps.workstreams)
+        return okText("recall_workstream is not available in this deployment.");
+    try {
+        const idOrLabel = (input.idOrLabel ?? "").trim();
+        if (!idOrLabel)
+            return okText("Provide a workstream id or label.");
+        const conversationId = resolveConversationByQuery(idOrLabel) ?? undefined;
+        const ws = deps.workstreams.store;
+        const found = (await ws.getById(idOrLabel)) ?? (await ws.findByNormalizedLabel(normalizeLabel(idOrLabel)));
+        if (!found)
+            return okText(`No workstream matches "${idOrLabel}".`);
+        const view = await rollupWorkstream({ workstreams: deps.workstreams.store, sessions: deps.workstreams.sessions, facts: deps.workstreams.facts, exemplars: deps.workstreams.exemplars }, found.id);
+        if (!view)
+            return okText(`No workstream matches "${idOrLabel}".`);
+        void logQuery({
+            source: "mcp",
+            runtime,
+            query: idOrLabel,
+            entity: null,
+            kind: null,
+            mode: "keyword",
+            limit: 1,
+            nResults: 1,
+            returnedIds: [found.id],
+            ...(conversationId !== undefined ? { conversationId } : {}),
+        });
+        return okText(composeWorkstreamRecall(view));
+    }
+    catch (e) {
+        return err(e);
+    }
+}
+/** idOrLabel -> live survivor workstream (merged_into resolved) | null. One source of truth for lifecycle handlers. */
+async function resolveWorkstream(store, idOrLabel) {
+    const found = (await store.getById(idOrLabel)) ?? (await store.findByNormalizedLabel(normalizeLabel(idOrLabel)));
+    if (!found)
+        return null;
+    const all = await store.listAll();
+    const byId = new Map(all.map((w) => [w.id, { id: w.id, mergedInto: w.mergedInto }]));
+    const survivorId = resolveWorkstreamId(found.id, byId);
+    return survivorId === found.id ? found : ((await store.getById(survivorId)) ?? found);
+}
+export async function renameWorkstreamHandler(deps, input) {
+    if (!deps.workstreams)
+        return okText("rename_workstream is not available in this deployment.");
+    try {
+        const idOrLabel = (input.idOrLabel ?? "").trim();
+        const label = (input.label ?? "").trim();
+        if (!idOrLabel || !label)
+            return okText("Provide the workstream (id or label) and the new label.");
+        const ws = deps.workstreams.store;
+        const target = await resolveWorkstream(ws, idOrLabel);
+        if (!target)
+            return okText(`No workstream matches "${idOrLabel}".`);
+        const collision = await ws.findByNormalizedLabel(normalizeLabel(label));
+        if (collision && collision.id !== target.id) {
+            return okText(`Label "${label}" is already used by workstream "${collision.label}" (${collision.id}).`);
+        }
+        await ws.setLabel(target.id, label);
+        return okText(`Renamed workstream ${target.id}: "${target.label}" -> "${label}".`);
+    }
+    catch (e) {
+        return err(e);
+    }
+}
+export async function retireWorkstreamHandler(deps, input) {
+    if (!deps.workstreams)
+        return okText("retire_workstream is not available in this deployment.");
+    try {
+        const idOrLabel = (input.idOrLabel ?? "").trim();
+        if (!idOrLabel)
+            return okText("Provide a workstream id or label.");
+        const target = await resolveWorkstream(deps.workstreams.store, idOrLabel);
+        if (!target)
+            return okText(`No workstream matches "${idOrLabel}".`);
+        await deps.workstreams.store.setStatus(target.id, "retired");
+        return okText(`Retired workstream "${target.label}" (${target.id}).`);
+    }
+    catch (e) {
+        return err(e);
+    }
+}
+export async function mergeWorkstreamsHandler(deps, input) {
+    if (!deps.workstreams)
+        return okText("merge_workstreams is not available in this deployment.");
+    try {
+        const fromArg = (input.from ?? "").trim();
+        const intoArg = (input.into ?? "").trim();
+        if (!fromArg || !intoArg)
+            return okText("Provide both `from` and `into` (workstream id or label).");
+        const ws = deps.workstreams.store;
+        const from = await resolveWorkstream(ws, fromArg);
+        const into = await resolveWorkstream(ws, intoArg);
+        if (!from)
+            return okText(`No workstream matches "${fromArg}".`);
+        if (!into)
+            return okText(`No workstream matches "${intoArg}".`);
+        if (from.id === into.id)
+            return okText(`"${fromArg}" and "${intoArg}" resolve to the same workstream — nothing to merge.`);
+        await ws.merge(from.id, into.id);
+        return okText(`Merged "${from.label}" (${from.id}) into "${into.label}" (${into.id}).`);
+    }
+    catch (e) {
+        return err(e);
+    }
+}
+export async function rebindSessionHandler(deps, input) {
+    if (!deps.workstreams)
+        return okText("rebind_session is not available in this deployment.");
+    try {
+        const sessionId = (input.sessionId ?? "").trim();
+        const wsArg = (input.workstream ?? "").trim();
+        if (!sessionId || !wsArg)
+            return okText("Provide both a sessionId and a workstream (id or label).");
+        const ws = await resolveWorkstream(deps.workstreams.store, wsArg);
+        if (!ws)
+            return okText(`No workstream matches "${wsArg}".`);
+        await deps.store.setWorkstreamBinding(sessionId, ws.id, "operator", null);
+        return okText(`Rebound session ${sessionId} -> workstream "${ws.label}" (${ws.id}).`);
+    }
+    catch (e) {
+        return err(e);
+    }
+}
+/** YYYY-MM-DD for "today" in the process timezone. */
+function localToday() {
+    const d = new Date();
+    const mo = String(d.getMonth() + 1).padStart(2, "0");
+    const da = String(d.getDate()).padStart(2, "0");
+    return `${d.getFullYear()}-${mo}-${da}`;
+}
 export async function getSessionHandler(deps, input) {
     try {
         const session = await deps.store.getById(input.id);
@@ -135,13 +311,25 @@ export async function getSessionHandler(deps, input) {
                 };
             })()
             : null;
-        return ok({ ...session, supersedes, supersededBy });
+        // Isolated: the outcome rollup is enrichment, not the payload. A throw
+        // here (SQLITE_BUSY, stale handle, unmigrated db) must degrade to
+        // no-outcome, never fail the whole get_session call.
+        let outcome;
+        if (deps.outcomeDb) {
+            try {
+                outcome = await deriveOutcome(session.id, await buildSqliteOutcomeDeps(deps.outcomeDb));
+            }
+            catch {
+                outcome = undefined;
+            }
+        }
+        return ok({ ...session, supersedes, supersededBy, ...(outcome ? { outcome } : {}) });
     }
     catch (e) {
         return err(e);
     }
 }
-export async function recallFactsHandler(deps, input) {
+export async function recallFactsHandler(deps, input, runtime = null) {
     if (!deps.factRecall) {
         return err(new Error("fact recall not wired in this deployment"));
     }
@@ -161,9 +349,11 @@ export async function recallFactsHandler(deps, input) {
                 : {}),
         };
         const result = await deps.factRecall.search(query);
+        const conversationId = resolveConversationByQuery(input.query ?? "") ?? undefined;
         // Telemetry — see recallSessionsHandler. Fire-and-forget.
         void logFactQuery({
             source: "mcp",
+            runtime,
             query: input.query ?? null,
             subject: input.subject ?? null,
             predicate: input.predicate ?? null,
@@ -172,6 +362,7 @@ export async function recallFactsHandler(deps, input) {
             limit: input.limit ?? DEFAULT_LIMIT,
             nResults: result.total,
             returnedIds: result.results.map((r) => r.id),
+            ...(conversationId !== undefined ? { conversationId } : {}),
         });
         return ok(result);
     }
@@ -191,7 +382,7 @@ export async function getFactHistoryHandler(deps, input) {
         return err(e);
     }
 }
-const CITE_SESSION_DESCRIPTION = `Log that you used a previously-surfaced session in your response. Pass the session ID. This lets NLM learn which surfaced sessions are actually useful, training a per-operator reranker over time. Call after writing your response, with one cite per surfaced session you actually drew from.`;
+const CITE_SESSION_DESCRIPTION = `Log that you used a previously-surfaced session in your response. Pass the session ID. This feeds the recall precision metric, which measures what fraction of surfaced sessions were actually useful. Call after writing your response, with one cite per surfaced session you actually drew from.`;
 const RECALL_DESCRIPTION = `Search prior AI sessions across every runtime the user has connected (Claude Code,
 Hermes, pi, Codex, Gemini, Aider). Local-first, fast (~200-400ms warm), idempotent,
 safe to call eagerly. No rate limit; no cost per call.
@@ -232,7 +423,7 @@ Skip ONLY when the request is purely forward-looking with no plausible prior
 context — drafting wholly new content, naming something new, brainstorming
 greenfield ideas. When in doubt, call.
 
-When you reference a returned session in your response, call \`cite_session(id)\` to log it so the recall layer can learn what is useful.
+When you reference a returned session in your response, call \`cite_session(id)\` to log it so NLM can measure which surfaced sessions are useful.
 
 Args:
   - query: keyword(s) to search. Token-weighted match against label, decisions,
@@ -240,8 +431,8 @@ Args:
   - entity: filter to sessions tagged with this entity. Optional.
   - kind: "decision" or "open" — restrict to sessions containing that marker
           kind. Omit for any. Optional.
-  - mode: "hybrid" (default — keyword BM25 + semantic embeddings), "keyword", or
-          "semantic". Optional.
+  - mode: Defaults to keyword (FTS5 BM25); hybrid and semantic are available.
+          Optional.
   - limit: max results (1-100, default 10).`;
 const GET_SESSION_DESCRIPTION = `Fetch one full session by its canonical ID, including the conversational body.
 
@@ -253,6 +444,10 @@ run, or any quote you intend to reference verbatim.
 The recall_sessions digest is optimized for ranking and scanning; the full body
 contains the actual conversation transcript that produced the decision.
 
+When wired, the response includes an \`outcome\` object: whether the session's
+decision held, was overturned, was built upon, was re-derived later, or
+remains unobserved, plus the evidence tier/confidence behind that verdict.
+
 Args:
   - id: Canonical session ID returned by recall_sessions (e.g. "cc_abc123",
         "sess_pgvector"). Pass the id field from the recall_sessions result.`;
@@ -281,12 +476,12 @@ Superseded facts are excluded by default; call get_fact_history to walk
 the chain of how a value evolved ("when did X flip from Fastify to Hono?").
 
 Examples:
-  recall_facts(subject="mac-pro-llm-host", predicate="model")
-    → the model alias currently exposed on the Mac Pro LLM endpoint
+  recall_facts(subject="local-llm-host", predicate="model")
+    → the model alias currently exposed on the local LLM endpoint
   recall_facts(subject="nlm-memory-ts", predicate="framework")
     → the web framework picked for nlm-memory-ts
-  recall_facts(subject="goat-home-services")
-    → all known facts about the GOAT engagement
+  recall_facts(subject="acme-client")
+    → all known facts about the Acme engagement
   recall_facts(query="routing", kind="decision")
     → recent decision-kind facts mentioning routing
 
@@ -416,7 +611,9 @@ export async function citeSessionHandler(input) {
     }
     try {
         await appendCitation({
-            conversationId: input.conversation_id ?? "mcp_tool",
+            // Agents rarely pass conversation_id; resolve it server-side from the
+            // surfaced-memo so the citation joins to its hook fire (NLM #345).
+            conversationId: input.conversation_id ?? resolveConversationForSession(input.id) ?? "mcp_tool",
             citedId: input.id,
             kind: "tool_use",
             ...(input.reason !== undefined ? { responsePreview: input.reason } : {}),
@@ -427,6 +624,81 @@ export async function citeSessionHandler(input) {
         return err(e);
     }
 }
+const REPORT_OUTCOME_DESCRIPTION = `Record whether a session's decision held up or was overturned. THIS IS THE CONTRACT SURFACE for outcome signals: it writes the same append-only \`signals\` row that POST /api/signal writes (producer "mcp"), just over MCP instead of HTTP.
+
+Expected callers are deterministic producers: hooks, CI pipelines, and automation platforms confirming a build/deploy/test result against a prior session. Agents rarely self-report their own outcome; outcome should come from independent evidence, not the agent's opinion of its own work.
+
+Args:
+  - session_id or correlation_key: at least one required. session_id is the NLM session this outcome applies to. correlation_key is an external identifier (e.g. a CI run id) to use when no NLM session_id is known; it is recorded on the row for traceability but is not (yet) joined into the Tier-B outcome rollup.
+  - outcome: one of pass | fail | fix | exhausted, the same vocabulary POST /api/signal accepts.
+  - source_of_record: required. Identifies the deterministic system asserting this outcome (e.g. "ci:github-actions", "hook:post-tool-use", "n8n:deploy-workflow").
+  - detail: optional passthrough object for additional context.`;
+/** The kind stamped on rows this tool writes. Loosely, this row represents an
+ *  outcome *review* of a prior session's decision, and "review" is the closest
+ *  fit among the existing SignalKind vocabulary (gate|eval|review|test); no
+ *  literal "outcome" kind exists (see rollup.ts's own note on this same
+ *  ambiguity). Tier-A correlation in rollup.ts keys on session_id only, so
+ *  this choice does not affect verdict derivation. */
+const REPORT_OUTCOME_KIND = "review";
+export async function reportOutcomeHandler(deps, input) {
+    if (!input.session_id && !input.correlation_key) {
+        return err(new Error("session_id or correlation_key is required"));
+    }
+    if (!input.source_of_record || input.source_of_record.length === 0) {
+        return err(new Error("source_of_record is required"));
+    }
+    if (!deps.signalStore || deps.installScope === undefined) {
+        return err(new Error("signal store not available"));
+    }
+    try {
+        let signal = normalizeSignal({
+            kind: REPORT_OUTCOME_KIND,
+            producer: "mcp",
+            outcome: input.outcome,
+            session: input.session_id ?? null,
+            detail: {
+                ...(input.detail ?? {}),
+                source_of_record: input.source_of_record,
+                ...(input.correlation_key ? { correlation_key: input.correlation_key } : {}),
+            },
+        }, deps.installScope);
+        signal = await stampSignalScope(signal, { sessionScopeReader: deps.sessionScopeReader });
+        await deps.signalStore.insert(signal);
+        return ok({ recorded: true, id: signal.id, outcome: signal.outcome });
+    }
+    catch (e) {
+        return err(e);
+    }
+}
+export async function listMergeSuggestionsHandler(deps, input) {
+    if (!deps.workstreams)
+        return okText("list_merge_suggestions is not available in this deployment.");
+    try {
+        const minScore = typeof input.minScore === "number" ? input.minScore : 0.5;
+        const all = (await deps.workstreams.store.listAll()).filter((w) => w.status === "active");
+        if (all.length < 2)
+            return okText("Not enough active workstreams to suggest merges.");
+        const ids = all.map((w) => w.id);
+        const entMap = await deps.workstreams.store.entitiesFor(ids);
+        const items = await Promise.all(all.map(async (w) => ({
+            id: w.id, label: w.label,
+            entities: entMap.get(w.id) ?? [],
+            sessionIds: await deps.workstreams.sessions.listSessionIdsByWorkstreams([w.id]),
+        })));
+        const suggestions = suggestMerges(items, minScore);
+        if (suggestions.length === 0)
+            return okText(`No merge suggestions at or above score ${minScore}.`);
+        const lines = ["MERGE SUGGESTIONS:"];
+        for (const s of suggestions) {
+            lines.push(`  - ${(s.score).toFixed(2)}  "${s.aLabel}" (${s.aId}) ~ "${s.bLabel}" (${s.bId})  [entities ${s.sharedEntities}, sessions ${s.sharedSessions}, label ${(s.labelSimilarity).toFixed(2)}]`);
+        }
+        lines.push("", "Merge a pair with: merge_workstreams(from, into).");
+        return okText(lines.join("\n"));
+    }
+    catch (e) {
+        return err(e);
+    }
+}
 export function createMcpServer(deps) {
     const server = new McpServer({
         name: SERVER_NAME,
@@ -451,7 +723,7 @@ export function createMcpServer(deps) {
             mode: z
                 .enum(["keyword", "semantic", "hybrid"])
                 .optional()
-                .describe("Search mode. Defaults to hybrid (keyword BM25 + semantic embeddings)."),
+                .describe("Search mode. Defaults to keyword (FTS5 BM25); hybrid and semantic are available."),
             limit: z
                 .number()
                 .int()
@@ -463,6 +735,10 @@ export function createMcpServer(deps) {
                 .boolean()
                 .optional()
                 .describe("If true, run a small LLM rewrite on the query before search — extracts entities and strips conversational filler. Set true for vague natural-language queries ('that pgvector thing'); set false for exact-token queries. Defaults to true server-side for MCP callers; the hot-path HTTP hook caller forces it off regardless."),
+            workstream: z
+                .string()
+                .optional()
+                .describe("Filter to sessions bound to this workstream (id or label; merge chains resolve)."),
         },
         annotations: {
             readOnlyHint: true,
@@ -470,7 +746,7 @@ export function createMcpServer(deps) {
             idempotentHint: true,
             openWorldHint: true,
         },
-    }, async (args) => recallSessionsHandler(deps, args));
+    }, async (args) => recallSessionsHandler(deps, args, mcpRuntimeFromClient(server.server.getClientVersion())));
     server.registerTool("get_session", {
         title: "Get Full NLM Session",
         description: GET_SESSION_DESCRIPTION,
@@ -533,7 +809,7 @@ export function createMcpServer(deps) {
                 idempotentHint: true,
                 openWorldHint: true,
             },
-        }, async (args) => recallFactsHandler(deps, args));
+        }, async (args) => recallFactsHandler(deps, args, mcpRuntimeFromClient(server.server.getClientVersion())));
         server.registerTool("get_fact_history", {
             title: "Get Fact Supersedence History",
             description: GET_FACT_HISTORY_DESCRIPTION,
@@ -584,7 +860,7 @@ export function createMcpServer(deps) {
             reason: z
                 .string()
                 .optional()
-                .describe("Why this session was useful. Optional but encouraged — articulating the reason is a weak training signal."),
+                .describe("Why this session was useful. Optional but encouraged; the reason is recorded with the citation for later review."),
         },
         annotations: {
             readOnlyHint: false,
@@ -593,6 +869,39 @@ export function createMcpServer(deps) {
             openWorldHint: false,
         },
     }, async (args) => citeSessionHandler(args));
+    if (deps.signalStore && deps.installScope !== undefined) {
+        server.registerTool("report_outcome", {
+            title: "Report Session Outcome",
+            description: REPORT_OUTCOME_DESCRIPTION,
+            inputSchema: {
+                session_id: z
+                    .string()
+                    .optional()
+                    .describe("NLM session ID this outcome applies to. Required if correlation_key is omitted."),
+                correlation_key: z
+                    .string()
+                    .optional()
+                    .describe("External correlation identifier (e.g. a CI run id) when no NLM session_id is known. Required if session_id is omitted."),
+                outcome: z
+                    .enum(SIGNAL_OUTCOMES)
+                    .describe("pass = held. fail | fix | exhausted = overturned."),
+                source_of_record: z
+                    .string()
+                    .min(1)
+                    .describe("The deterministic system asserting this outcome (e.g. \"ci:github-actions\", \"hook:post-tool-use\")."),
+                detail: z
+                    .record(z.string(), z.unknown())
+                    .optional()
+                    .describe("Optional passthrough context, stored on the signal row."),
+            },
+            annotations: {
+                readOnlyHint: false,
+                destructiveHint: false,
+                idempotentHint: true,
+                openWorldHint: false,
+            },
+        }, async (args) => reportOutcomeHandler(deps, args));
+    }
     server.registerTool("mark_superseded", {
         title: "Mark NLM Session Superseded",
         description: MARK_SUPERSEDED_DESCRIPTION,
@@ -617,6 +926,65 @@ export function createMcpServer(deps) {
             openWorldHint: false,
         },
     }, async (args) => markSupersededHandler(deps, args));
+    server.registerTool("work_summary", {
+        title: "Daily work summary",
+        description: "The operator's agent-assisted work recap for a day: where attention went (active time by topic), focus quality (context switches, longest block), and progress (decisions, open loops). Optional `date` (YYYY-MM-DD); defaults to today.",
+        inputSchema: {
+            date: z
+                .string()
+                .regex(/^\d{4}-\d{2}-\d{2}$/)
+                .optional()
+                .describe("Day to summarize, YYYY-MM-DD. Defaults to today."),
+        },
+        annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false },
+    }, async (args) => workSummaryHandler(deps, args));
+    server.registerTool("recall_workstream", {
+        title: "Recall a workstream's accumulated context",
+        description: "Return the coherent project view for a workstream: its member sessions, current decisions and open loops, accumulated facts, and code exemplars. Accepts a workstream id or label; merge chains resolve to the live workstream.",
+        inputSchema: {
+            idOrLabel: z.string().describe("Workstream id (ws_...) or label (e.g. 'NLM')."),
+        },
+        annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false },
+    }, async (args) => recallWorkstreamHandler(deps, args, mcpRuntimeFromClient(server.server.getClientVersion())));
+    server.registerTool("rebind_session", {
+        title: "Rebind a session to a different workstream",
+        description: "Move a session's primary workstream binding (operator correction). Sets binding_source=operator. The session's facts and exemplars roll up under the new workstream automatically (rollup is by session binding).",
+        inputSchema: {
+            sessionId: z.string().describe("Session id to rebind."),
+            workstream: z.string().describe("Target workstream id (ws_...) or label."),
+        },
+        annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: false },
+    }, async (args) => rebindSessionHandler(deps, args));
+    server.registerTool("merge_workstreams", {
+        title: "Merge one workstream into another",
+        description: "Supersede a duplicate workstream into the one to keep: sets merged_into, marks it merged, and unions its entity index. Sessions, facts, and exemplars resolve to the survivor automatically (no session rewrite). Accepts ids or labels; merge chains resolve.",
+        inputSchema: {
+            from: z.string().describe("Workstream to retire (the duplicate); id or label."),
+            into: z.string().describe("Workstream to keep (the survivor); id or label."),
+        },
+        annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: false },
+    }, async (args) => mergeWorkstreamsHandler(deps, args));
+    server.registerTool("rename_workstream", {
+        title: "Rename a workstream",
+        description: "Relabel a workstream. Refuses a label that collides with a different existing workstream's normalized label (prevents accidental duplicates). Accepts id or label.",
+        inputSchema: {
+            idOrLabel: z.string().describe("Workstream id or current label."),
+            label: z.string().describe("New label."),
+        },
+        annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: false },
+    }, async (args) => renameWorkstreamHandler(deps, args));
+    server.registerTool("retire_workstream", {
+        title: "Retire a workstream",
+        description: "Mark a workstream retired (status=retired). Operator cleanup for dead one-off workstreams. Reversible by re-setting status. Accepts id or label.",
+        inputSchema: { idOrLabel: z.string().describe("Workstream id or label.") },
+        annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: false },
+    }, async (args) => retireWorkstreamHandler(deps, args));
+    server.registerTool("list_merge_suggestions", {
+        title: "Suggest duplicate workstreams to merge",
+        description: "Score active workstream pairs by shared entities, co-occurring sessions, and label similarity; list likely duplicates for one-click merge_workstreams. Computed on demand; read-only.",
+        inputSchema: { minScore: z.number().optional().describe("Minimum similarity score 0..1 (default 0.5).") },
+        annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false },
+    }, async (args) => listMergeSuggestionsHandler(deps, args));
     if (deps.exemplarStore &&
         deps.installScope &&
         process.env["NLM_CODE_EXEMPLARS_ENABLED"] === "1") {
@@ -666,6 +1034,23 @@ export function createMcpServer(deps) {
                 k: args.k ?? 5,
                 includeNegatives: args.include_negatives ?? true,
             }, exemplarStore, codeEmbedder, null);
+            const conversationId = resolveConversationByQuery(args.query) ?? undefined;
+            const allIds = [
+                ...result.positives.map((e) => e.id),
+                ...result.negatives.map((e) => e.id),
+            ];
+            void logQuery({
+                source: "mcp",
+                runtime: mcpRuntimeFromClient(server.server.getClientVersion()),
+                query: args.query,
+                entity: null,
+                kind: null,
+                mode: "semantic",
+                limit: args.k ?? 5,
+                nResults: allIds.length,
+                returnedIds: allIds,
+                ...(conversationId !== undefined ? { conversationId } : {}),
+            });
             return { content: [{ type: "text", text: format(result) }] };
         });
         server.registerTool("supersede_exemplar", {