exovault-mcp-server 1.2.0 → 1.3.0

package/dist/gateway-client.d.ts

@@ -62,6 +62,12 @@ export declare class GatewayClient {
         includeArchived?: boolean;
         entity?: string;
         compact?: boolean;
+        decayHalfLife?: number;
+        diversity?: number;
+        searchMode?: "auto" | "hybrid" | "bm25" | "semantic";
+        graphWeight?: number;
+        graphSeeds?: number;
+        graphMaxHops?: number;
     }): Promise<string>;
     readMemories(memoryIds: string[]): Promise<string>;
     updateMemory(params: {

package/dist/index.js

@@ -605,6 +605,9 @@ async function main() {
             compact: s(z.boolean().optional().describe("Return truncated content previews (200 chars) instead of full content. Use read_memories for full content on specific IDs.")),
             decayHalfLife: s(z.number().int().min(1).max(365).optional().describe("Temporal decay half-life in days (default 30). Older memories score lower unless importance >= 4.")),
             diversity: s(z.number().min(0).max(1).optional().describe("MMR diversity balance 0-1 (default 0.7). Higher = more relevance, lower = more diversity.")),
+            graphWeight: s(z.number().min(0).max(1.5).optional().describe("RRF weight for graph signal (default 0.6). Set 0 to disable graph expansion.")),
+            graphSeeds: s(z.number().int().min(0).max(15).optional().describe("How many top results to use as graph expansion seeds (default 5)")),
+            graphMaxHops: s(z.number().int().min(1).max(2).optional().describe("Max hops for graph traversal (default 1)")),
         },
     }, auto.wrap(wrapToolHandler(async (args) => {
         const input = args;

package/dist/tools/search-memories.d.ts

@@ -11,4 +11,7 @@ export declare function searchMemories(ctx: McpContext, input: {
     decayHalfLife?: number;
     diversity?: number;
     searchMode?: "auto" | "hybrid" | "bm25" | "semantic";
+    graphWeight?: number;
+    graphSeeds?: number;
+    graphMaxHops?: number;
 }): Promise<string>;

package/dist/tools/search-memories.js

@@ -12,13 +12,27 @@ import { applyImportanceBoostBatch } from "./importance-boost.js";
 import { applyConfidenceDampenBatch } from "./confidence-dampen.js";
 const FALLBACK_CONTENT_PREVIEW_CHARS = 500;
 const COMPACT_CONTENT_CHARS = 200;
+function buildSignalsMap(lists) {
+    const map = new Map();
+    for (const [signal, ids] of Object.entries(lists)) {
+        if (!ids)
+            continue;
+        for (const id of ids) {
+            const existing = map.get(id);
+            if (existing)
+                existing.push(signal);
+            else
+                map.set(id, [signal]);
+        }
+    }
+    return map;
+}
 // RRF signal weights
 const WEIGHT_SEMANTIC = 1.0;
 const WEIGHT_BM25 = 0.9;
 const WEIGHT_BLIND_INDEX = 0.4;
-const WEIGHT_GRAPH = 0.6;
-// Graph expansion: how many initial results to expand, and relation weights
-const GRAPH_EXPAND_TOP_N = 5;
+// WEIGHT_GRAPH and GRAPH_EXPAND_TOP_N are now configurable via input params (defaults applied inline)
+// Graph relation weights for scoring neighbor relevance
 const GRAPH_RELATION_WEIGHTS = {
     refines: 1.0,
     derived_from: 0.9,
@@ -90,6 +104,7 @@ export async function searchMemories(ctx, input) {
                 supersededById: m.superseded_by_id,
                 entities: m.entities,
                 updatedAt: m.updated_at,
+                signals: ["entity"],
                 ...(attachmentLines.length > 0 ? { attachments: attachmentLines } : {}),
             };
         }));
@@ -187,30 +202,47 @@ export async function searchMemories(ctx, input) {
     await Promise.all([semanticPromise, blindPromise, bm25Promise]);
     // ── Signal 3: Graph expansion on top-N unique results from all signals ─
     const graphIds = [];
-    const initialHits = new Set([...semanticIds, ...blindIds, ...bm25Ids]);
-    const seedIds = [...initialHits].slice(0, GRAPH_EXPAND_TOP_N);
-    if (seedIds.length > 0) {
-        try {
-            const graphResults = await Promise.all(seedIds.map((id) => getKnowledgeGraph(ctx.supabase, ctx.userId, "memory", id, 1, 10)));
-            // Collect neighbor memory IDs ranked by relation weight
-            const neighborScores = new Map();
-            for (const neighbors of graphResults) {
-                for (const n of neighbors) {
-                    if (n.node_type !== "memory" || initialHits.has(n.node_id))
-                        continue;
-                    const weight = GRAPH_RELATION_WEIGHTS[n.relation] ?? 0.5;
-                    const current = neighborScores.get(n.node_id) ?? 0;
-                    neighborScores.set(n.node_id, Math.max(current, weight));
+    const graphWeight = input.graphWeight ?? 0.6;
+    // Graph expansion — skip entirely when graphWeight=0
+    if (graphWeight > 0) {
+        const initialHits = new Set([...semanticIds, ...blindIds, ...bm25Ids]);
+        const graphSeedCount = input.graphSeeds ?? 5;
+        const seedIds = [...initialHits].slice(0, graphSeedCount);
+        if (seedIds.length > 0) {
+            try {
+                const graphMaxHops = input.graphMaxHops ?? 1;
+                const maxNodesPerSeed = graphMaxHops >= 2 ? 25 : 10;
+                const graphResults = await Promise.all(seedIds.map((id) => getKnowledgeGraph(ctx.supabase, ctx.userId, "memory", id, graphMaxHops, maxNodesPerSeed)));
+                // Collect neighbor memory IDs ranked by relation weight
+                const neighborScores = new Map();
+                for (const neighbors of graphResults) {
+                    for (const n of neighbors) {
+                        if (n.node_type !== "memory")
+                            continue;
+                        // Only exclude seed IDs — allow boosting of already-found results (aligned with gateway)
+                        if (seedIds.includes(n.node_id))
+                            continue;
+                        const weight = GRAPH_RELATION_WEIGHTS[n.relation] ?? 0.5;
+                        const current = neighborScores.get(n.node_id) ?? 0;
+                        neighborScores.set(n.node_id, Math.max(current, weight));
+                    }
                 }
+                graphIds.push(...Array.from(neighborScores.entries())
+                    .sort((a, b) => b[1] - a[1])
+                    .map(([id]) => id));
+            }
+            catch (err) {
+                process.stderr.write(`[search-memories] Graph expansion error: ${err instanceof Error ? err.message : String(err)}\n`);
             }
-            graphIds.push(...Array.from(neighborScores.entries())
-                .sort((a, b) => b[1] - a[1])
-                .map(([id]) => id));
-        }
-        catch (err) {
-            process.stderr.write(`[search-memories] Graph expansion error: ${err instanceof Error ? err.message : String(err)}\n`);
         }
     }
+    // ── Signal attribution ──────────────────────────────────────────────
+    const signalsMap = buildSignalsMap({
+        semantic: semanticIds,
+        bm25: bm25Ids,
+        blind: blindIds,
+        graph: graphIds,
+    });
     // ── RRF Fusion + Temporal Decay ──────────────────────────────────────
     let rankedIds = [];
     let searchMode = "hybrid";
@@ -225,7 +257,7 @@ export async function searchMemories(ctx, input) {
         if (blindIds.length > 0)
             lists.push({ ids: blindIds, weight: WEIGHT_BLIND_INDEX });
         if (graphIds.length > 0)
-            lists.push({ ids: graphIds, weight: WEIGHT_GRAPH });
+            lists.push({ ids: graphIds, weight: graphWeight });
         // Get scored candidates — fetch topK*2 for decay re-ranking headroom, with top-rank bonus
         const rrfScored = fuseWithRRFScored(lists, 60, true).slice(0, topK * 2);
         searchMode = effectiveSearchMode === "bm25" ? "bm25"
@@ -336,6 +368,7 @@ export async function searchMemories(ctx, input) {
             supersededById: m.superseded_by_id,
             entities: m.entities,
             updatedAt: m.updated_at,
+            signals: signalsMap.get(m.id) ?? [],
             ...(attachmentLines.length > 0 ? { attachments: attachmentLines } : {}),
         };
     }));

package/dist/tools/search-notes.d.ts

@@ -1,4 +1,13 @@
 import type { McpContext } from "../auth.js";
+/**
+ * Direct-mode note search: keyword matching via blind-index pre-filter (when mekHex
+ * is available) or full client-side scan. Scores by weighted term frequency
+ * (title 3x, tags 2x, content 1x).
+ *
+ * NOTE: `searchMode`, `threshold`, and `diversity` are accepted for API compatibility
+ * but are IGNORED in direct mode. Hybrid/semantic/graph search modes and MMR
+ * diversity re-ranking require gateway mode (POST /api/agent/search-notes).
+ */
 export declare function searchNotes(ctx: McpContext, input: {
     query: string;
     topK?: number;

package/dist/tools/search-notes.js

@@ -42,6 +42,15 @@ function scoreNote(terms, title, tags, content) {
 }
 const COMPACT_PREVIEW_CHARS = 200;
 const FULL_PREVIEW_CHARS = 500;
+/**
+ * Direct-mode note search: keyword matching via blind-index pre-filter (when mekHex
+ * is available) or full client-side scan. Scores by weighted term frequency
+ * (title 3x, tags 2x, content 1x).
+ *
+ * NOTE: `searchMode`, `threshold`, and `diversity` are accepted for API compatibility
+ * but are IGNORED in direct mode. Hybrid/semantic/graph search modes and MMR
+ * diversity re-ranking require gateway mode (POST /api/agent/search-notes).
+ */
 export async function searchNotes(ctx, input) {
     const topK = input.topK ?? 10;
     const vaultId = input.vaultId;

package/dist/tools/search.d.ts

@@ -1,4 +1,5 @@
 import type { McpContext } from "../auth.js";
+import { GatewayClient } from "../gateway-client.js";
 interface SearchParams {
     query: string;
     topK?: number;
@@ -7,7 +8,6 @@ interface SearchParams {
     diversity?: number;
     vaultId?: string;
     includeContent?: boolean;
-    compact?: boolean;
     scope?: "all" | "memories" | "notes";
     memoryType?: string;
     includeArchived?: boolean;
@@ -16,12 +16,13 @@ interface SearchParams {
 /**
  * Universal search tool — searches memories, notes, or both.
  *
- * In direct mode: best-effort — calls searchMemories and/or searchNotes
- * independently and interleaves results (no cross-type MMR).
+ * In gateway mode: delegates to POST /api/agent/search which performs full
+ * cross-type MMR re-ranking server-side (hybrid semantic + keyword, all modes).
  *
- * Note: In gateway mode, the MCP server's `search` tool registration in index.ts
- * delegates to the gateway `/api/agent/search` endpoint which performs full
- * cross-type MMR re-ranking server-side. This function is only used in direct mode.
+ * In direct mode: best-effort — calls searchMemories and/or searchNotes
+ * independently and interleaves results (no cross-type MMR). searchMode,
+ * threshold, and diversity are passed through but only partially honoured
+ * (notes fall back to keyword+blind-index only; see searchNotes).
  */
-export declare function search(ctx: McpContext, params: SearchParams): Promise<string>;
+export declare function search(ctx: McpContext, params: SearchParams, gw?: GatewayClient): Promise<string>;
 export {};

package/dist/tools/search.js

@@ -3,14 +3,19 @@ import { searchNotes } from "./search-notes.js";
 /**
  * Universal search tool — searches memories, notes, or both.
  *
- * In direct mode: best-effort — calls searchMemories and/or searchNotes
- * independently and interleaves results (no cross-type MMR).
+ * In gateway mode: delegates to POST /api/agent/search which performs full
+ * cross-type MMR re-ranking server-side (hybrid semantic + keyword, all modes).
  *
- * Note: In gateway mode, the MCP server's `search` tool registration in index.ts
- * delegates to the gateway `/api/agent/search` endpoint which performs full
- * cross-type MMR re-ranking server-side. This function is only used in direct mode.
+ * In direct mode: best-effort — calls searchMemories and/or searchNotes
+ * independently and interleaves results (no cross-type MMR). searchMode,
+ * threshold, and diversity are passed through but only partially honoured
+ * (notes fall back to keyword+blind-index only; see searchNotes).
  */
-export async function search(ctx, params) {
+export async function search(ctx, params, gw) {
+    // Gateway mode: full cross-type MMR re-ranking server-side
+    if (gw) {
+        return gw.search(params);
+    }
     const scope = params.scope ?? "all";
     const topK = params.topK ?? 10;
     const searchMemoriesParams = {
@@ -20,7 +25,6 @@ export async function search(ctx, params) {
         vaultId: params.vaultId,
         memoryType: params.memoryType,
         includeArchived: params.includeArchived,
-        compact: params.compact,
         decayHalfLife: params.decayHalfLife,
         diversity: params.diversity,
         searchMode: params.searchMode,
@@ -33,7 +37,6 @@ export async function search(ctx, params) {
         diversity: params.diversity,
         vaultId: params.vaultId,
         includeContent: params.includeContent,
-        compact: params.compact,
     };
     try {
         if (scope === "memories") {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "exovault-mcp-server",
-  "version": "1.2.0",
+  "version": "1.3.0",
   "type": "module",
   "description": "MCP server for ExoVault — read, search, and manage encrypted notes from Claude Code",
   "main": "dist/index.js",