@mneme-ai/mcp 1.24.2 → 1.25.0

package/dist/tools/_registry.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"_registry.d.ts","sourceRoot":"","sources":["../../src/tools/_registry.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAmC3D;sEACsE;AACtE,wBAAgB,aAAa,IAAI,SAAS,EAAE,CAqC3C;AAED,mDAAmD;AACnD,wBAAgB,YAAY,IAAI,GAAG,CAAC,MAAM,EAAE,SAAS,CAAC,CASrD;AAED,uEAAuE;AACvE,wBAAgB,eAAe,IAAI,GAAG,CAAC,YAAY,EAAE,SAAS,EAAE,CAAC,CAOhE"}
+{"version":3,"file":"_registry.d.ts","sourceRoot":"","sources":["../../src/tools/_registry.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAoC3D;sEACsE;AACtE,wBAAgB,aAAa,IAAI,SAAS,EAAE,CAsC3C;AAED,mDAAmD;AACnD,wBAAgB,YAAY,IAAI,GAAG,CAAC,MAAM,EAAE,SAAS,CAAC,CASrD;AAED,uEAAuE;AACvE,wBAAgB,eAAe,IAAI,GAAG,CAAC,YAAY,EAAE,SAAS,EAAE,CAAC,CAOhE"}

package/dist/tools/_registry.js

@@ -37,6 +37,7 @@ import { nucleusTools } from "./_nucleus.js";
 import { inboxTools } from "./_inbox.js";
 import { antivirusTools } from "./_antivirus.js";
 import { whatsNewTool } from "./_whats_new.js";
+import { retrievalLabTools } from "./_retrieval_lab.js";
 /** All Mneme tools, in display order. The capabilities syllabus comes first
  *  so AI clients that read tool lists top-down see it immediately. */
 export function buildAllTools() {
@@ -65,6 +66,7 @@ export function buildAllTools() {
         ...inboxTools,
         ...antivirusTools,
         whatsNewTool,
+        ...retrievalLabTools,
         smartDoTool,
         ...memoryTools,
         ...peopleTools,

package/dist/tools/_registry.js.map

@@ -1 +1 @@
-{"version":3,"file":"_registry.js","sourceRoot":"","sources":["../../src/tools/_registry.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"_registry.js","sourceRoot":"","sources":["../../src/tools/_registry.ts"],"names":[],"mappings":"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"}

package/dist/tools/_retrieval_lab.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Mneme Retrieval Lab -- MCP tools.
+ *
+ *   mneme.retrieval.lab.list_configs   -- arm pool + active config
+ *   mneme.retrieval.lab.leaderboard    -- ranked by mean composite + UCB1
+ *   mneme.retrieval.lab.tune           -- run one trial on demand
+ *   mneme.retrieval.cross_encoder.rerank -- rerank candidates with bge-reranker-base
+ *   mneme.retrieval.hyde.rewrite       -- expand query via HyDE
+ */
+import type { MnemeTool } from "./_types.js";
+export declare const labListConfigsTool: MnemeTool;
+export declare const labLeaderboardTool: MnemeTool;
+export declare const labTuneTool: MnemeTool;
+export declare const crossEncoderRerankTool: MnemeTool;
+export declare const hydeRewriteTool: MnemeTool;
+export declare const retrievalLabTools: MnemeTool[];
+//# sourceMappingURL=_retrieval_lab.d.ts.map

package/dist/tools/_retrieval_lab.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"_retrieval_lab.d.ts","sourceRoot":"","sources":["../../src/tools/_retrieval_lab.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAGH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAI7C,eAAO,MAAM,kBAAkB,EAAE,SAsChC,CAAC;AAEF,eAAO,MAAM,kBAAkB,EAAE,SAoChC,CAAC;AAEF,eAAO,MAAM,WAAW,EAAE,SA+BzB,CAAC;AAEF,eAAO,MAAM,sBAAsB,EAAE,SA4CpC,CAAC;AAEF,eAAO,MAAM,eAAe,EAAE,SA6C7B,CAAC;AAEF,eAAO,MAAM,iBAAiB,EAAE,SAAS,EAMxC,CAAC"}

package/dist/tools/_retrieval_lab.js

@@ -0,0 +1,213 @@
+/**
+ * Mneme Retrieval Lab -- MCP tools.
+ *
+ *   mneme.retrieval.lab.list_configs   -- arm pool + active config
+ *   mneme.retrieval.lab.leaderboard    -- ranked by mean composite + UCB1
+ *   mneme.retrieval.lab.tune           -- run one trial on demand
+ *   mneme.retrieval.cross_encoder.rerank -- rerank candidates with bge-reranker-base
+ *   mneme.retrieval.hyde.rewrite       -- expand query via HyDE
+ */
+import { retrievalLab } from "@mneme-ai/core";
+const ROOT = (rt) => rt.meta.rootPath;
+export const labListConfigsTool = {
+    name: "mneme.retrieval.lab.list_configs",
+    category: "meta",
+    description: "List the candidate retrieval configs the auto-tuner picks among, " +
+        "plus the currently-active config (the one every search() in Mneme " +
+        "uses right now). Configs vary on embedder backend, RRF k, vector/BM25 " +
+        "weight, reranker, HyDE on/off, and candidate-K.",
+    whenToUse: "User asks 'what retrieval configs are running?' or 'why is search slow?'",
+    triggers: ["retrieval configs", "retrieval lab", "what retrieval"],
+    inputSchema: { type: "object", properties: {} },
+    outputSchema: {
+        type: "object",
+        properties: {
+            configs: { type: "array" }, active: { type: "string" }, total: { type: "number" },
+        },
+    },
+    examples: [{ userQuery: "What retrieval configs is Mneme trying?" }],
+    pitfalls: [
+        "Paid embedders (voyage-3, openai-3-*) only appear active if API keys are present in the env.",
+    ],
+    composeWith: ["mneme.retrieval.lab.leaderboard", "mneme.retrieval.lab.tune"],
+    handler: async (rt) => {
+        const lb = retrievalLab.readLeaderboard(ROOT(rt));
+        const available = retrievalLab.availableEmbedders().map((e) => e.id);
+        return {
+            data: {
+                configs: retrievalLab.CANDIDATE_CONFIGS.map((c) => ({
+                    ...c,
+                    available: available.includes(c.embedder),
+                })),
+                active: lb.active,
+                total: retrievalLab.CANDIDATE_CONFIGS.length,
+            },
+            wisdom: `${retrievalLab.CANDIDATE_CONFIGS.length} candidate configs; active = "${lb.active}". ${available.length} embedder backends usable on this machine.`,
+            confidence: { level: "high" },
+        };
+    },
+};
+export const labLeaderboardTool = {
+    name: "mneme.retrieval.lab.leaderboard",
+    category: "meta",
+    description: "Show the auto-tuner leaderboard: each config + trial count + mean " +
+        "precision/recall/NDCG/latency + UCB1. The current active config is " +
+        "the highest-mean entry with at least 2 trials. Pareto frontier (best " +
+        "tradeoff between quality and latency) is included separately.",
+    whenToUse: "Inspect the auto-tuner's progress; explain why config X is active.",
+    triggers: ["retrieval leaderboard", "retrieval pareto", "retrieval tuning state"],
+    inputSchema: { type: "object", properties: {} },
+    outputSchema: {
+        type: "object",
+        properties: { entries: { type: "array" }, active: { type: "string" }, totalTrials: { type: "number" }, paretoIds: { type: "array" } },
+    },
+    examples: [{ userQuery: "Which retrieval config is winning right now?" }],
+    pitfalls: [
+        "Configs with trialCount=0 show ucb1=Infinity by design (untried arms get priority).",
+    ],
+    composeWith: ["mneme.retrieval.lab.tune", "mneme.retrieval.lab.list_configs"],
+    handler: async (rt) => {
+        const lb = retrievalLab.readLeaderboard(ROOT(rt));
+        const pareto = retrievalLab.paretoFrontier(lb).map((e) => e.configId);
+        const tried = lb.entries.filter((e) => e.trialCount > 0)
+            .sort((a, b) => b.meanComposite - a.meanComposite);
+        return {
+            data: {
+                entries: lb.entries, active: lb.active, totalTrials: lb.totalTrials,
+                paretoIds: pareto,
+            },
+            wisdom: tried.length === 0
+                ? `Leaderboard is empty -- start the daemon (\`mneme nucleus daemon --detach\`) and trials will run automatically every 15 min.`
+                : `${tried.length} configs tried (${lb.totalTrials} trials). Active: "${lb.active}" (composite ${tried[0]?.meanComposite.toFixed(3)}, latency ${Math.round(tried[0]?.meanLatencyMs ?? 0)}ms).`,
+            confidence: { level: "high" },
+        };
+    },
+};
+export const labTuneTool = {
+    name: "mneme.retrieval.lab.tune",
+    category: "meta",
+    description: "Run ONE retrieval-config trial on demand. Picks the next arm via " +
+        "UCB1 (or accepts a specific configId), runs the eval suite, folds " +
+        "the result into the leaderboard. Each trial is HMAC-SHA256 signed.",
+    whenToUse: "Force a trial without waiting for the daemon's 15-min cycle.",
+    triggers: ["tune retrieval", "retrieval trial", "rerun tuner"],
+    inputSchema: {
+        type: "object",
+        properties: { configId: { type: "string", description: "Optional: trial this exact config. Default: UCB1 picks." } },
+    },
+    outputSchema: { type: "object", properties: { trial: { type: "object" }, newActive: { type: "string" } } },
+    examples: [{ userQuery: "Run one retrieval-tuning trial." }],
+    pitfalls: [],
+    composeWith: ["mneme.retrieval.lab.leaderboard"],
+    handler: async (rt, args) => {
+        const root = ROOT(rt);
+        const wantId = typeof args["configId"] === "string" ? args["configId"] : null;
+        const config = wantId
+            ? retrievalLab.getConfig(wantId)
+            : retrievalLab.pickNextArm(retrievalLab.readLeaderboard(root)).config;
+        const trial = retrievalLab.runTrial(root, config);
+        const lb = retrievalLab.recordTrial(root, trial);
+        return {
+            data: { trial, newActive: lb.active },
+            wisdom: `Trial of "${config.id}" complete: composite ${trial.compositeScore.toFixed(3)}, latency ${trial.meanLatencyMs}ms. Active config = "${lb.active}".`,
+            confidence: { level: "high" },
+        };
+    },
+};
+export const crossEncoderRerankTool = {
+    name: "mneme.retrieval.cross_encoder.rerank",
+    category: "meta",
+    description: "Rerank a list of candidate texts using bge-reranker-base (a cross-" +
+        "encoder transformer). Cross-encoders score (query, candidate) pairs " +
+        "JOINTLY and consistently lift NDCG@10 by 5-15% on retrieval tasks " +
+        "(at the cost of ~30-100ms per candidate on CPU). Use AFTER first-" +
+        "stage retrieval to refine the top results.",
+    whenToUse: "You have ~10-50 candidate chunks and want a higher-precision top-K.",
+    triggers: ["cross-encoder rerank", "rerank with bge", "reranker"],
+    inputSchema: {
+        type: "object",
+        required: ["query", "candidates"],
+        properties: {
+            query: { type: "string" },
+            candidates: {
+                type: "array",
+                items: { type: "object", required: ["id", "text"], properties: { id: { type: "string" }, text: { type: "string" } } },
+            },
+            topK: { type: "number" },
+        },
+    },
+    outputSchema: { type: "object", properties: { ranked: { type: "array" }, totalMs: { type: "number" }, modelLoaded: { type: "boolean" } } },
+    examples: [{ userQuery: "Rerank these 20 commit chunks against 'how does auth handle expired tokens?'" }],
+    pitfalls: [
+        "First call loads the bge-reranker-base WASM model (~50MB), can take 5-15s. Subsequent calls are fast (cached).",
+        "Falls back to term-density scoring if @huggingface/transformers can't be loaded.",
+    ],
+    composeWith: ["mneme.retrieval.hyde.rewrite", "mneme.retrieval.lab.tune"],
+    handler: async (_rt, args) => {
+        const r = await retrievalLab.rerankCrossEncoder({
+            query: String(args["query"] ?? ""),
+            candidates: args["candidates"] ?? [],
+            topK: typeof args["topK"] === "number" ? args["topK"] : undefined,
+        });
+        return {
+            data: r,
+            wisdom: r.modelLoaded
+                ? `Reranked ${r.ranked.length} candidates in ${r.totalMs}ms via bge-reranker-base.`
+                : `Cross-encoder unavailable; fell back to term-density (${r.fallbackReason ?? "unknown"}).`,
+            confidence: { level: r.modelLoaded ? "high" : "medium" },
+        };
+    },
+};
+export const hydeRewriteTool = {
+    name: "mneme.retrieval.hyde.rewrite",
+    category: "meta",
+    description: "Apply HyDE (Hypothetical Document Embeddings) query rewrite: returns " +
+        "a system-prompt payload the AI agent uses to generate a hypothetical " +
+        "ANSWER, OR -- if the agent already supplied one -- returns the " +
+        "wrapped result ready for embedding. Lifts retrieval recall on most " +
+        "corpora without any extra deps.",
+    whenToUse: "Before embedding a query for retrieval, especially when the question is abstract or natural-language.",
+    triggers: ["hyde rewrite", "expand query", "hypothetical embedding"],
+    inputSchema: {
+        type: "object",
+        required: ["query"],
+        properties: {
+            query: { type: "string" },
+            agentSuppliedRewrite: { type: "string", description: "Optional: AI's hypothetical answer if already generated." },
+            mode: { type: "string", enum: ["prompt", "apply"], description: "'prompt' returns the system-prompt payload; 'apply' returns the rewrite (using agentSuppliedRewrite or deterministic fallback)." },
+        },
+    },
+    outputSchema: { type: "object", properties: { mode: { type: "string" }, payload: { type: "object" } } },
+    examples: [{ userQuery: "HyDE-rewrite this query: 'how does auth handle expired tokens?'" }],
+    pitfalls: [
+        "Deterministic fallback (no agent rewrite) is less effective than a real LLM rewrite -- best to loop back: get prompt -> generate -> resubmit with agentSuppliedRewrite.",
+    ],
+    composeWith: ["mneme.retrieval.cross_encoder.rerank"],
+    handler: async (_rt, args) => {
+        const query = String(args["query"] ?? "");
+        const mode = (args["mode"] === "apply" ? "apply" : "prompt");
+        if (mode === "prompt") {
+            const payload = retrievalLab.buildHyDePrompt(query);
+            return {
+                data: { mode: "prompt", payload },
+                wisdom: `HyDE prompt ready. Generate a hypothetical answer (${payload.maxChars} chars max), then call this tool again with mode='apply' + agentSuppliedRewrite.`,
+                confidence: { level: "high" },
+            };
+        }
+        const supplied = typeof args["agentSuppliedRewrite"] === "string" ? args["agentSuppliedRewrite"] : null;
+        const result = retrievalLab.applyHyde(query, supplied);
+        return {
+            data: { mode: "apply", payload: result },
+            wisdom: `HyDE rewrite (${result.source}): "${result.rewritten.slice(0, 80)}..."`,
+            confidence: { level: result.source === "agent-supplied" ? "high" : "medium" },
+        };
+    },
+};
+export const retrievalLabTools = [
+    labListConfigsTool,
+    labLeaderboardTool,
+    labTuneTool,
+    crossEncoderRerankTool,
+    hydeRewriteTool,
+];
+//# sourceMappingURL=_retrieval_lab.js.map

package/dist/tools/_retrieval_lab.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"_retrieval_lab.js","sourceRoot":"","sources":["../../src/tools/_retrieval_lab.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mneme-ai/mcp",
-  "version": "1.24.2",
+  "version": "1.25.0",
   "description": "MCP server that exposes Mneme to Claude Code, Cursor, Continue, and other AI clients",
   "type": "module",
   "main": "./dist/index.js",
@@ -45,8 +45,8 @@
     "node": ">=22.13.0 <25.0.0"
   },
   "dependencies": {
-    "@mneme-ai/core": "1.24.2",
-    "@mneme-ai/embeddings": "1.24.2",
+    "@mneme-ai/core": "1.25.0",
+    "@mneme-ai/embeddings": "1.25.0",
     "@modelcontextprotocol/sdk": "^1.0.4"
   }
 }