exovault-mcp-server 1.0.2 → 1.1.1

package/dist/gateway-client.d.ts

@@ -291,6 +291,16 @@ export declare class GatewayClient {
         documentType: "soul" | "instructions" | "skills" | "checks";
         vaultId?: string;
     }): Promise<string>;
+    recall(params: {
+        mode: "temporal" | "topic" | "graph";
+        range?: string;
+        query?: string;
+        searchMode?: "auto" | "hybrid" | "bm25" | "semantic";
+        topK?: number;
+        nodeId?: string;
+        maxHops?: number;
+        vaultId?: string;
+    }): Promise<string>;
     readDocs(params: {
         slug?: string;
         list?: boolean;

package/dist/gateway-client.js

@@ -274,6 +274,11 @@ export class GatewayClient {
         const result = await this.request("POST", "/api/agent/read-document", params);
         return JSON.stringify(result);
     }
+    // ─── Recall ──────────────────────────────────────────────────────────────
+    async recall(params) {
+        const result = await this.request("POST", "/api/agent/recall", params);
+        return JSON.stringify(result);
+    }
     async readDocs(params) {
         const result = await this.request("POST", "/api/agent/read-docs", params);
         return JSON.stringify(result);

package/dist/index.js

@@ -1,5 +1,7 @@
 #!/usr/bin/env node
 import { randomUUID } from "node:crypto";
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { z } from "zod";
@@ -27,6 +29,7 @@ import { updateMemoryTool } from "./tools/update-memory.js";
 import { cleanupMemories } from "./tools/cleanup-memories.js";
 import { getLinks, addLink, removeLink } from "./tools/knowledge-links.js";
 import { exploreGraph } from "./tools/explore-graph.js";
+import { recall } from "./tools/recall.js";
 import { sendMessage, ackMessage, readMessages } from "./tools/agent-messages.js";
 // Task tools are thin wrappers around memory tools — no separate agent-tasks import needed
 import { resolveVaultId } from "./tools/resolve-vault-id.js";
@@ -50,6 +53,30 @@ const MEMORY_TYPES = ["fact", "skill", "preference", "constraint", "task", "epis
 const memoryTypeEnum = z.enum(MEMORY_TYPES);
 /** Remind agents to checkpoint every N tool calls. */
 const CHECKPOINT_REMINDER_INTERVAL = 20;
+/** Max age (ms) of the hook session file to be considered valid. */
+const HOOK_SESSION_MAX_AGE_MS = 120_000;
+/**
+ * Read the session ID written by the SessionStart hook.
+ * Returns null if the file is missing, stale (>120s), or invalid.
+ */
+function readHookSessionId() {
+    try {
+        const home = process.env.HOME || process.env.USERPROFILE || "~";
+        const filePath = join(home, ".exovault-mcp", "current-session.json");
+        const raw = readFileSync(filePath, "utf8");
+        const data = JSON.parse(raw);
+        if (data.sessionId &&
+            data.timestamp &&
+            Date.now() - data.timestamp < HOOK_SESSION_MAX_AGE_MS) {
+            process.stderr.write(`[exovault-mcp] Using hook session ID: ${data.sessionId}\n`);
+            return data.sessionId;
+        }
+    }
+    catch {
+        // File doesn't exist or is invalid — fall back to random UUID
+    }
+    return null;
+}
 async function main() {
     // ─── Detect mode: gateway (agent key) or direct (Supabase) ─────────────
     const config = await readConfig();
@@ -60,10 +87,10 @@ async function main() {
     let allowedVaultIds;
     let gwAgentType;
     let gwAgentLabel;
-    // Generate a unique session ID for this MCP server instance.
-    // Used as the default agentRunId so all memories from one connection
-    // are grouped into the same session — even if the agent doesn't pass one.
-    const sessionRunId = randomUUID();
+    // Try to reuse the session ID written by the SessionStart hook so that
+    // MCP tool calls and hook-captured turns share the same dashboard session.
+    // Falls back to a random UUID if the hook file is missing or stale.
+    const sessionRunId = readHookSessionId() ?? randomUUID();
     if (gwConfig) {
         gw = new GatewayClient(gwConfig.apiUrl, gwConfig.agentKey, sessionRunId);
         try {
@@ -689,7 +716,7 @@ async function main() {
                 })).optional(),
                 sourceNoteIds: z.array(z.string().uuid()).optional(),
                 supersededById: z.string().uuid().optional(),
-            })).max(50).describe("Array of memories to save (0-50). Can be empty when only sessionSummary is provided.")),
+            })).max(50).default([]).describe("Memories to bulk-save (0-50). Defaults to empty array — omit or pass [] when only sessionSummary is needed.")),
             sessionSummary: s(z.string().min(1).describe("REQUIRED. Narrative summary of what happened this session — what was discussed, decided, and accomplished. Saved as an episodic memory. Do NOT write tool call stats — describe the work in human terms.")),
             vaultId: s(z.string().uuid().optional().describe("Vault/project scope for all memories. Required unless defaultVaultId is configured.")),
             agentId: s(z.string().optional().describe("Agent identifier")),
@@ -1168,6 +1195,32 @@ async function main() {
         }
         return await readMessages(ctx, { ...input, agentId, vaultId: resolveVaultId(ctx, input.vaultId) });
     })));
+    // ─── recall ─────────────────────────────────────────────────────────────
+    server.registerTool("recall", {
+        description: "Deep context retrieval with three modes: " +
+            "temporal (session timeline by date range), " +
+            "topic (hybrid BM25+semantic search across memories), " +
+            "graph (knowledge graph expansion from query or node). " +
+            "Use session_start for basic warm-up; use recall for targeted deep retrieval mid-session.",
+        inputSchema: {
+            mode: s(z.enum(["temporal", "topic", "graph"]).describe("temporal: chronological session timeline by date range. " +
+                "topic: hybrid BM25+semantic search across memories. " +
+                "graph: knowledge graph expansion from query or node.")),
+            range: s(z.string().optional().describe("Temporal mode: 'today', 'yesterday', 'last_week', 'last_3_days', 'last_N_days', or ISO date '2026-03-01'")),
+            query: s(z.string().max(2000).optional().describe("Topic/graph mode: search query")),
+            searchMode: s(z.enum(["auto", "hybrid", "bm25", "semantic"]).optional().describe("Topic mode: search strategy. Default: 'hybrid'")),
+            topK: s(z.number().int().min(1).max(50).optional().describe("Topic mode: max results. Default: 10")),
+            nodeId: s(z.string().uuid().optional().describe("Graph mode: start from this node")),
+            maxHops: s(z.number().int().min(1).max(5).optional().describe("Graph mode: traversal depth. Default: 2")),
+            vaultId: s(z.string().uuid().optional().describe("Scope to vault")),
+        },
+    }, auto.wrap(wrapToolHandler(async (args) => {
+        const input = args;
+        if (gw) {
+            return await gw.recall({ ...input, vaultId: resolveVault(input.vaultId) });
+        }
+        return await recall(ctx, { ...input, vaultId: resolveVaultId(ctx, input.vaultId) });
+    })));
     // ─── Orphan recovery — flush crashed sessions from previous runs ─────────
     try {
         const orphans = await scanOrphanedBuffers(10);

package/dist/setup.js

@@ -1,13 +1,94 @@
 #!/usr/bin/env node
 import { createClient } from "@supabase/supabase-js";
 import { createInterface } from "node:readline";
-import { mkdir, writeFile } from "node:fs/promises";
-import { join } from "node:path";
-import { homedir } from "node:os";
+import { copyFile, mkdir, writeFile } from "node:fs/promises";
+import { dirname, join } from "node:path";
+import { homedir, platform } from "node:os";
 import { parseArgs } from "node:util";
+import { fileURLToPath } from "node:url";
 import { deriveWrappingKey, unwrapMasterKey, importMasterKey, bufferToHex, } from "./crypto.js";
 const CONFIG_DIR = join(homedir(), ".exovault-mcp");
 const CONFIG_FILE = join(CONFIG_DIR, "config.json");
+const HOOKS_DIR = join(CONFIG_DIR, "hooks");
+const IS_WINDOWS = platform() === "win32";
+/** Returns platform-appropriate MCP server config snippet. */
+function getMcpServerConfig() {
+    if (IS_WINDOWS) {
+        return {
+            mcpServers: {
+                exovault: {
+                    command: "cmd",
+                    args: ["/c", "npx", "-y", "exovault-mcp-server"],
+                },
+            },
+        };
+    }
+    return {
+        mcpServers: {
+            exovault: {
+                command: "npx",
+                args: ["-y", "exovault-mcp-server"],
+            },
+        },
+    };
+}
+/** Returns hook config snippet for turn capture. */
+function getHooksConfig() {
+    const hookPath = "~/.exovault-mcp/hooks/capture-turn.js";
+    return {
+        hooks: {
+            UserPromptSubmit: [{
+                    matcher: "",
+                    hooks: [{
+                            type: "command",
+                            command: `node ${hookPath} user`,
+                            timeout: 15,
+                        }],
+                }],
+            Stop: [{
+                    matcher: "",
+                    hooks: [{
+                            type: "command",
+                            command: `node ${hookPath} assistant`,
+                            timeout: 15,
+                        }],
+                }],
+        },
+    };
+}
+/** Copies capture-turn.js hook to ~/.exovault-mcp/hooks/ */
+async function installHook() {
+    try {
+        await mkdir(HOOKS_DIR, { recursive: true, mode: 0o700 });
+        // Resolve the bundled hook relative to this file's package
+        const thisDir = dirname(fileURLToPath(import.meta.url));
+        const srcHook = join(thisDir, "..", "hooks", "capture-turn.js");
+        const destHook = join(HOOKS_DIR, "capture-turn.js");
+        await copyFile(srcHook, destHook);
+        console.log(`Turn capture hook installed to: ${destHook}`);
+        return true;
+    }
+    catch (err) {
+        console.warn("Could not install turn capture hook:", err instanceof Error ? err.message : err);
+        return false;
+    }
+}
+/** Prints Claude Code config snippet + optional hook instructions. */
+function printSetupInstructions(hookInstalled) {
+    console.log();
+    console.log("Add this to your project's .mcp.json or ~/.claude/settings.json:");
+    console.log();
+    console.log(JSON.stringify(getMcpServerConfig(), null, 2));
+    if (hookInstalled) {
+        console.log();
+        console.log("Optional: Add turn capture hooks to .claude/settings.json for richer memory:");
+        console.log("(Captures full conversation context — not just MCP tool calls)");
+        console.log();
+        console.log(JSON.stringify(getHooksConfig(), null, 2));
+    }
+    console.log();
+    console.log("Setup complete! Restart Claude Code to connect.");
+}
 function printUsage() {
     console.log("Usage:");
     console.log("  exovault-mcp-server setup --agent-key <key> [--api-url <url>]   (gateway mode)");
@@ -90,20 +171,8 @@ async function setupGatewayMode(agentKey, apiUrl) {
     });
     console.log();
     console.log(`Config saved to: ${CONFIG_FILE}`);
-    // Print Claude Code config snippet
-    console.log();
-    console.log("Add this to your ~/.claude/settings.json (mcpServers section):");
-    console.log();
-    console.log(JSON.stringify({
-        mcpServers: {
-            exovault: {
-                command: "npx",
-                args: ["exovault-mcp-server"],
-            },
-        },
-    }, null, 2));
-    console.log();
-    console.log("Setup complete! Restart Claude Code to connect.");
+    const hookInstalled = await installHook();
+    printSetupInstructions(hookInstalled);
 }
 async function main() {
     // Parse CLI args
@@ -237,20 +306,8 @@ async function main() {
         rl3.close();
         await writeFile(CONFIG_FILE, JSON.stringify(config, null, 2), { encoding: "utf-8", mode: 0o600 });
         console.log(`Config saved to: ${CONFIG_FILE}`);
-        // Print Claude Code config snippet
-        console.log();
-        console.log("Add this to your ~/.claude/settings.json (mcpServers section):");
-        console.log();
-        console.log(JSON.stringify({
-            mcpServers: {
-                exovault: {
-                    command: "npx",
-                    args: ["exovault-mcp-server"],
-                },
-            },
-        }, null, 2));
-        console.log();
-        console.log("Setup complete! Restart Claude Code to connect.");
+        const hookInstalled = await installHook();
+        printSetupInstructions(hookInstalled);
     }
     catch (err) {
         console.error("Setup failed:", err instanceof Error ? err.message : err);

package/dist/tools/bm25.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Normalize a BM25 score (from PostgreSQL ts_rank_cd) to 0-1 range.
+ * Formula from QMD: score / (1 + score).
+ * Maps: 0→0, 1→0.5, 9→0.9, asymptotically approaches 1.
+ */
+export declare function normalizeBm25(raw: number): number;

package/dist/tools/bm25.js

@@ -0,0 +1,10 @@
+/**
+ * Normalize a BM25 score (from PostgreSQL ts_rank_cd) to 0-1 range.
+ * Formula from QMD: score / (1 + score).
+ * Maps: 0→0, 1→0.5, 9→0.9, asymptotically approaches 1.
+ */
+export function normalizeBm25(raw) {
+    if (raw <= 0)
+        return 0;
+    return raw / (1 + raw);
+}

package/dist/tools/confidence-dampen.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Post-RRF confidence dampening for memory search results.
+ *
+ * Multiplies each candidate's score by a factor derived from its confidence level.
+ * Confidence 5 (verified) is neutral (1.0×), confidence 1 (speculative) gets a 40% penalty.
+ *
+ * Formula: multiplier = 0.5 + 0.5 * (confidence / 5)
+ */
+/**
+ * Compute the confidence multiplier for a given confidence level (1-5).
+ * conf 1 → 0.6, conf 3 → 0.8, conf 5 → 1.0
+ */
+export declare function computeConfidenceMultiplier(confidence: number): number;
+export interface DampenedCandidate {
+    id: string;
+    score: number;
+}
+/**
+ * Apply confidence dampening to a batch of scored candidates and re-sort.
+ * Candidates missing from confidenceMap default to confidence 3.
+ */
+export declare function applyConfidenceDampenBatch(candidates: {
+    id: string;
+    score: number;
+}[], confidenceMap: Map<string, number>): DampenedCandidate[];

package/dist/tools/confidence-dampen.js

@@ -0,0 +1,29 @@
+/**
+ * Post-RRF confidence dampening for memory search results.
+ *
+ * Multiplies each candidate's score by a factor derived from its confidence level.
+ * Confidence 5 (verified) is neutral (1.0×), confidence 1 (speculative) gets a 40% penalty.
+ *
+ * Formula: multiplier = 0.5 + 0.5 * (confidence / 5)
+ */
+/**
+ * Compute the confidence multiplier for a given confidence level (1-5).
+ * conf 1 → 0.6, conf 3 → 0.8, conf 5 → 1.0
+ */
+export function computeConfidenceMultiplier(confidence) {
+    return 0.5 + 0.5 * (confidence / 5);
+}
+/**
+ * Apply confidence dampening to a batch of scored candidates and re-sort.
+ * Candidates missing from confidenceMap default to confidence 3.
+ */
+export function applyConfidenceDampenBatch(candidates, confidenceMap) {
+    if (candidates.length === 0)
+        return [];
+    return candidates
+        .map((c) => ({
+        id: c.id,
+        score: c.score * computeConfidenceMultiplier(confidenceMap.get(c.id) ?? 3),
+    }))
+        .sort((a, b) => b.score - a.score);
+}

package/dist/tools/importance-boost.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Post-RRF importance boost for memory search results.
+ *
+ * Multiplies each candidate's score by a factor derived from its importance level.
+ * Importance 3 is neutral (1.0×), importance 5 gets a 15% boost, importance 1 gets a 15% penalty.
+ *
+ * Formula: multiplier = 1 + 0.15 * (importance - 3) / 2
+ */
+/**
+ * Compute the importance multiplier for a given importance level (1-5).
+ * imp 1 → 0.85, imp 3 → 1.0, imp 5 → 1.15
+ */
+export declare function computeImportanceMultiplier(importance: number): number;
+export interface BoostedCandidate {
+    id: string;
+    score: number;
+}
+/**
+ * Apply importance boost to a batch of scored candidates and re-sort.
+ * Candidates missing from importanceMap default to importance 3 (neutral).
+ */
+export declare function applyImportanceBoostBatch(candidates: {
+    id: string;
+    score: number;
+}[], importanceMap: Map<string, number>): BoostedCandidate[];

package/dist/tools/importance-boost.js

@@ -0,0 +1,29 @@
+/**
+ * Post-RRF importance boost for memory search results.
+ *
+ * Multiplies each candidate's score by a factor derived from its importance level.
+ * Importance 3 is neutral (1.0×), importance 5 gets a 15% boost, importance 1 gets a 15% penalty.
+ *
+ * Formula: multiplier = 1 + 0.15 * (importance - 3) / 2
+ */
+/**
+ * Compute the importance multiplier for a given importance level (1-5).
+ * imp 1 → 0.85, imp 3 → 1.0, imp 5 → 1.15
+ */
+export function computeImportanceMultiplier(importance) {
+    return 1 + 0.15 * (importance - 3) / 2;
+}
+/**
+ * Apply importance boost to a batch of scored candidates and re-sort.
+ * Candidates missing from importanceMap default to importance 3 (neutral).
+ */
+export function applyImportanceBoostBatch(candidates, importanceMap) {
+    if (candidates.length === 0)
+        return [];
+    return candidates
+        .map((c) => ({
+        id: c.id,
+        score: c.score * computeImportanceMultiplier(importanceMap.get(c.id) ?? 3),
+    }))
+        .sort((a, b) => b.score - a.score);
+}

package/dist/tools/recall.d.ts

@@ -0,0 +1,24 @@
+import type { McpContext } from "../auth.js";
+export interface RecallInput {
+    mode: "temporal" | "topic" | "graph";
+    range?: string;
+    query?: string;
+    searchMode?: "auto" | "hybrid" | "bm25" | "semantic";
+    topK?: number;
+    nodeId?: string;
+    maxHops?: number;
+    vaultId?: string;
+}
+/** Parse temporal range string to start/end dates. */
+export declare function parseTemporalRange(range: string, now?: Date): {
+    start: Date;
+    end: Date;
+};
+/** Group memories into morning/afternoon/evening and format as timeline. */
+export declare function formatTimeline(memories: {
+    summary?: string | null;
+    content?: string;
+    createdAt: string;
+}[], dateLabel: string): string;
+/** Main recall function — routes to temporal/topic/graph mode. */
+export declare function recall(ctx: McpContext, input: RecallInput): Promise<string>;

package/dist/tools/recall.js

@@ -0,0 +1,146 @@
+import { searchMemories } from "./search-memories.js";
+import { exploreGraph } from "./explore-graph.js";
+import { decryptMemoryFields } from "./decrypt-helpers.js";
+/** Parse temporal range string to start/end dates. */
+export function parseTemporalRange(range, now = new Date()) {
+    const todayStart = new Date(now);
+    todayStart.setUTCHours(0, 0, 0, 0);
+    switch (range) {
+        case "today": {
+            return { start: todayStart, end: now };
+        }
+        case "yesterday": {
+            const start = new Date(todayStart);
+            start.setUTCDate(start.getUTCDate() - 1);
+            return { start, end: todayStart };
+        }
+        case "last_week": {
+            const start = new Date(todayStart);
+            start.setUTCDate(start.getUTCDate() - 7);
+            return { start, end: now };
+        }
+        default: {
+            // Match "last_N_days" pattern
+            const match = range.match(/^last_(\d+)_days$/);
+            if (match) {
+                const days = parseInt(match[1], 10);
+                const start = new Date(todayStart);
+                start.setUTCDate(start.getUTCDate() - days);
+                return { start, end: now };
+            }
+            // ISO date: "2026-02-15"
+            const start = new Date(range + "T00:00:00.000Z");
+            const end = new Date(start);
+            end.setUTCDate(end.getUTCDate() + 1);
+            return { start, end };
+        }
+    }
+}
+/** Group memories into morning/afternoon/evening and format as timeline. */
+export function formatTimeline(memories, dateLabel) {
+    const periods = {
+        "Morning (00:00-12:00)": [],
+        "Afternoon (12:00-18:00)": [],
+        "Evening (18:00-24:00)": [],
+    };
+    for (const m of memories) {
+        const hour = new Date(m.createdAt).getUTCHours();
+        if (hour < 12)
+            periods["Morning (00:00-12:00)"].push(m);
+        else if (hour < 18)
+            periods["Afternoon (12:00-18:00)"].push(m);
+        else
+            periods["Evening (18:00-24:00)"].push(m);
+    }
+    const lines = [`## Timeline: ${dateLabel}\n`];
+    for (const [period, items] of Object.entries(periods)) {
+        if (items.length === 0)
+            continue;
+        lines.push(`### ${period}`);
+        for (const item of items) {
+            const time = new Date(item.createdAt).toISOString().slice(11, 16);
+            const text = item.summary || item.content || "(no summary)";
+            lines.push(`- [${time}] ${text}`);
+        }
+        lines.push("");
+    }
+    return lines.join("\n");
+}
+/** Main recall function — routes to temporal/topic/graph mode. */
+export async function recall(ctx, input) {
+    switch (input.mode) {
+        case "temporal":
+            return recallTemporal(ctx, input);
+        case "topic":
+            return recallTopic(ctx, input);
+        case "graph":
+            return recallGraph(ctx, input);
+        default:
+            return JSON.stringify({ error: `Unknown mode: ${input.mode}` });
+    }
+}
+async function recallTemporal(ctx, input) {
+    if (!input.range) {
+        return JSON.stringify({ error: "temporal mode requires 'range' parameter" });
+    }
+    const { start, end } = parseTemporalRange(input.range);
+    // Query episodic memories in date range via Supabase
+    const { data, error } = await ctx.supabase
+        .from("memories")
+        .select("id, encrypted_content, content_iv, encrypted_summary, summary_iv, memory_type, importance, created_at")
+        .eq("user_id", ctx.userId)
+        .eq("memory_type", "episodic")
+        .gte("created_at", start.toISOString())
+        .lte("created_at", end.toISOString())
+        .order("created_at", { ascending: true });
+    if (error || !data || data.length === 0) {
+        return JSON.stringify({
+            mode: "temporal",
+            range: input.range,
+            sessions: [],
+            message: "No sessions found in this range.",
+        });
+    }
+    // Decrypt summaries
+    const decrypted = await Promise.all(data.map(async (row) => {
+        let summary = "";
+        try {
+            if (row.encrypted_summary && row.summary_iv) {
+                const dec = await decryptMemoryFields({ encrypted_summary: row.encrypted_summary, summary_iv: row.summary_iv }, ctx.masterKey);
+                summary = dec.summary || "";
+            }
+            if (!summary && row.encrypted_content && row.content_iv) {
+                const dec = await decryptMemoryFields({ encrypted_content: row.encrypted_content, content_iv: row.content_iv }, ctx.masterKey);
+                summary = dec.content.slice(0, 300);
+            }
+        }
+        catch {
+            summary = "(decryption failed)";
+        }
+        return { summary, createdAt: row.created_at };
+    }));
+    const dateLabel = start.toISOString().slice(0, 10);
+    return formatTimeline(decrypted, dateLabel);
+}
+async function recallTopic(ctx, input) {
+    if (!input.query) {
+        return JSON.stringify({ error: "topic mode requires 'query' parameter" });
+    }
+    return searchMemories(ctx, {
+        query: input.query,
+        topK: input.topK ?? 10,
+        searchMode: input.searchMode ?? "hybrid",
+        vaultId: input.vaultId,
+    });
+}
+async function recallGraph(ctx, input) {
+    if (!input.query && !input.nodeId) {
+        return JSON.stringify({ error: "graph mode requires 'query' or 'nodeId'" });
+    }
+    return exploreGraph(ctx, {
+        query: input.query,
+        nodeId: input.nodeId,
+        maxHops: input.maxHops ?? 2,
+        vaultId: input.vaultId,
+    });
+}

package/dist/tools/relevance.d.ts

@@ -0,0 +1,13 @@
+export interface ScoredResult {
+    id: string;
+    score: number;
+    relevance?: number;
+}
+/**
+ * Normalize RRF scores to 0-100 relevance.
+ * Top result = 100, others proportional.
+ * Input must be sorted by score descending.
+ */
+export declare function normalizeToRelevance<T extends ScoredResult>(results: T[]): (T & {
+    relevance: number;
+})[];

package/dist/tools/relevance.js

@@ -0,0 +1,17 @@
+/**
+ * Normalize RRF scores to 0-100 relevance.
+ * Top result = 100, others proportional.
+ * Input must be sorted by score descending.
+ */
+export function normalizeToRelevance(results) {
+    if (results.length === 0)
+        return [];
+    const maxScore = results[0].score;
+    if (maxScore <= 0) {
+        return results.map((r) => ({ ...r, relevance: 0 }));
+    }
+    return results.map((r) => ({
+        ...r,
+        relevance: Math.round((r.score / maxScore) * 100),
+    }));
+}

package/dist/tools/rrf.d.ts

@@ -25,4 +25,4 @@ export declare function fuseWithRRF(rankedLists: {
 export declare function fuseWithRRFScored(rankedLists: {
     ids: string[];
     weight: number;
-}[], k?: number): RRFScoredResult[];
+}[], k?: number, topRankBonus?: boolean): RRFScoredResult[];

package/dist/tools/rrf.js

@@ -5,12 +5,27 @@ export function fuseWithRRF(rankedLists, k = 60) {
  * Like fuseWithRRF but returns { id, score } pairs for downstream re-ranking
  * (e.g. temporal decay, MMR).
  */
-export function fuseWithRRFScored(rankedLists, k = 60) {
+export function fuseWithRRFScored(rankedLists, k = 60, topRankBonus = false) {
     const scores = new Map();
+    const bestRank = new Map();
     for (const list of rankedLists) {
         for (let i = 0; i < list.ids.length; i++) {
             const id = list.ids[i];
             scores.set(id, (scores.get(id) ?? 0) + list.weight / (k + i + 1));
+            const prev = bestRank.get(id);
+            if (prev === undefined || i < prev) {
+                bestRank.set(id, i);
+            }
+        }
+    }
+    if (topRankBonus) {
+        for (const [id, rank] of bestRank) {
+            if (rank === 0) {
+                scores.set(id, scores.get(id) + 0.05);
+            }
+            else if (rank <= 2) {
+                scores.set(id, scores.get(id) + 0.02);
+            }
         }
     }
     return [...scores.entries()]

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

@@ -10,4 +10,5 @@ export declare function searchMemories(ctx: McpContext, input: {
     compact?: boolean;
     decayHalfLife?: number;
     diversity?: number;
+    searchMode?: "auto" | "hybrid" | "bm25" | "semantic";
 }): Promise<string>;

package/dist/tools/search-memories.js

@@ -7,11 +7,14 @@ import { generateBlindTokens } from "./blind-index.js";
 import { fuseWithRRFScored } from "./rrf.js";
 import { applyTemporalDecayBatch, } from "./temporal-decay.js";
 import { selectMMR } from "./mmr.js";
+import { applyImportanceBoostBatch } from "./importance-boost.js";
+import { applyConfidenceDampenBatch } from "./confidence-dampen.js";
 const FALLBACK_CONTENT_PREVIEW_CHARS = 500;
 const COMPACT_CONTENT_CHARS = 200;
 // RRF signal weights
 const WEIGHT_SEMANTIC = 1.0;
-const WEIGHT_BLIND_INDEX = 0.8;
+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;
@@ -31,7 +34,7 @@ function clip(text, maxChars) {
 }
 export async function searchMemories(ctx, input) {
     const topK = input.topK ?? 10;
-    const threshold = input.threshold ?? 0.4;
+    const threshold = input.threshold ?? 0.5;
     // Entity-based search: use JSONB containment instead of semantic search
     if (input.entity) {
         const entityResults = await searchMemoriesByEntity(ctx.supabase, ctx.userId, input.entity, topK);
@@ -80,15 +83,19 @@ export async function searchMemories(ctx, input) {
         });
         return payload;
     }
+    const effectiveSearchMode = input.searchMode ?? "auto";
+    const useBm25 = effectiveSearchMode !== "semantic";
+    const useSemantic = effectiveSearchMode !== "bm25";
     let embeddingTokens = 0;
     const semanticIds = [];
     const semanticScores = new Map();
     const blindIds = [];
+    const bm25Ids = [];
     let semanticError = null;
     const embeddingConfig = resolveEmbeddingConfig(ctx);
-    // ── Signal 1 + Signal 2: run in parallel ──────────────────────────────
+    // ── Signal 1 + Signal 2 + Signal 4: run in parallel ──────────────────
     const semanticPromise = (async () => {
-        if (!embeddingConfig)
+        if (!embeddingConfig || !useSemantic)
             return;
         try {
             embeddingTokens = Math.ceil(input.query.length / 4);
@@ -130,10 +137,31 @@ export async function searchMemories(ctx, input) {
             process.stderr.write(`[search-memories] Blind index search error: ${err instanceof Error ? err.message : String(err)}\n`);
         }
     })();
-    await Promise.all([semanticPromise, blindPromise]);
-    // ── Signal 3: Graph expansion on top-N unique results from signals 1+2 ─
+    const bm25Promise = (async () => {
+        if (!useBm25)
+            return;
+        try {
+            const { data, error } = await ctx.supabase.rpc("match_memories_bm25", {
+                p_user_id: ctx.userId,
+                p_query: input.query,
+                p_vault_id: input.vaultId ?? null,
+                p_match_count: topK * 4,
+                p_include_archived: input.includeArchived ?? false,
+            });
+            if (error || !data)
+                return;
+            for (const r of data) {
+                bm25Ids.push(r.memory_id);
+            }
+        }
+        catch (err) {
+            process.stderr.write(`[search-memories] BM25 search error: ${err instanceof Error ? err.message : String(err)}\n`);
+        }
+    })();
+    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]);
+    const initialHits = new Set([...semanticIds, ...blindIds, ...bm25Ids]);
     const seedIds = [...initialHits].slice(0, GRAPH_EXPAND_TOP_N);
     if (seedIds.length > 0) {
         try {
@@ -161,24 +189,34 @@ export async function searchMemories(ctx, input) {
     let rankedIds = [];
     let searchMode = "hybrid";
     const halfLife = input.decayHalfLife ?? 30;
-    const hasSignals = semanticIds.length > 0 || blindIds.length > 0;
+    const hasSignals = semanticIds.length > 0 || blindIds.length > 0 || bm25Ids.length > 0;
     if (hasSignals) {
         const lists = [];
         if (semanticIds.length > 0)
             lists.push({ ids: semanticIds, weight: WEIGHT_SEMANTIC });
+        if (bm25Ids.length > 0)
+            lists.push({ ids: bm25Ids, weight: WEIGHT_BM25 });
         if (blindIds.length > 0)
             lists.push({ ids: blindIds, weight: WEIGHT_BLIND_INDEX });
         if (graphIds.length > 0)
             lists.push({ ids: graphIds, weight: WEIGHT_GRAPH });
-        // Get scored candidates — fetch topK*2 for decay re-ranking headroom
-        const rrfScored = fuseWithRRFScored(lists).slice(0, topK * 2);
-        searchMode = lists.length === 1 && semanticIds.length > 0 ? "semantic" : "hybrid";
-        // Fetch candidate rows for updatedAt + importance
+        // 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"
+            : lists.length === 1 && semanticIds.length > 0 ? "semantic"
+                : "hybrid";
+        // Fetch candidate rows for updatedAt + importance + confidence
         const candidateIds = rrfScored.map((r) => r.id);
         const candidateRows = await getMemoriesByIds(ctx.supabase, ctx.userId, candidateIds);
         const candidateMap = new Map(candidateRows.map((r) => [r.id, r]));
+        // Build importance and confidence maps for boost/dampen
+        const importanceMap = new Map(candidateRows.map((r) => [r.id, r.importance]));
+        const confidenceMap = new Map(candidateRows.map((r) => [r.id, r.confidence]));
+        // Apply importance boost then confidence dampen (before temporal decay)
+        const boosted = applyImportanceBoostBatch(rrfScored, importanceMap);
+        const dampened = applyConfidenceDampenBatch(boosted, confidenceMap);
         // Build scored candidates and apply temporal decay
-        const scoredCandidates = rrfScored
+        const scoredCandidates = dampened
             .filter((r) => candidateMap.has(r.id))
             .map((r) => {
             const row = candidateMap.get(r.id);
@@ -249,15 +287,23 @@ export async function searchMemories(ctx, input) {
     }));
     // Track access for returned results (fire-and-forget)
     touchMemories(ctx.supabase, ctx.userId, results.map((r) => r.id));
+    // Add 0-100 relevance scores (top result = 100, proportional by position)
+    const withRelevance = results.map((m, i) => ({
+        ...m,
+        relevance: results.length > 0
+            ? Math.round(((results.length - i) / results.length) * 100)
+            : 0,
+    }));
     const payload = JSON.stringify({
         searchMode,
         compact: input.compact ?? false,
         threshold,
         semanticMatchCount: semanticIds.length,
         blindIndexMatchCount: blindIds.length,
+        bm25MatchCount: bm25Ids.length,
         graphExpansionCount: graphIds.length,
         semanticError,
-        memories: results,
+        memories: withRelevance,
     }, null, 2);
     await logMcpUsageEvent({
         supabase: ctx.supabase,

package/hooks/capture-turn.js

@@ -0,0 +1,175 @@
+#!/usr/bin/env node
+/* eslint-disable @typescript-eslint/no-require-imports */
+/**
+ * ExoVault turn capture hook for Claude Code.
+ * Captures user prompts and assistant responses, POSTs to ingest-turn API.
+ *
+ * Usage (called by Claude Code hooks, not directly):
+ *   echo '{"prompt":"hello"}' | node capture-turn.js user
+ *   echo '{"last_assistant_message":"hi"}' | node capture-turn.js assistant
+ *
+ * Config resolution (first match wins):
+ *   1. EXOVAULT_AGENT_KEY / EXOVAULT_API_URL env vars
+ *   2. ~/.exovault-mcp/config.json (agentKey / apiUrl fields)
+ */
+
+const path = require("path");
+const fs = require("fs");
+
+const MAX_CONTENT_LENGTH = 50_000;
+const MIN_CONTENT_LENGTH = 5;
+const FETCH_TIMEOUT_MS = 10_000;
+
+/** Default config file path — same as the MCP server. */
+const CONFIG_PATH = path.join(
+  process.env.HOME || process.env.USERPROFILE || "~",
+  ".exovault-mcp",
+  "config.json",
+);
+
+/**
+ * Resolve agent key and API URL from env vars, falling back to config file.
+ * Returns { agentKey, apiUrl } or null if not configured.
+ */
+function resolveConfig() {
+  // 1. Env vars take priority
+  let agentKey = process.env.EXOVAULT_AGENT_KEY || "";
+  let apiUrl = process.env.EXOVAULT_API_URL || "";
+
+  // 2. Fall back to config file
+  if (!agentKey) {
+    try {
+      const raw = fs.readFileSync(CONFIG_PATH, "utf8");
+      const config = JSON.parse(raw);
+      if (!agentKey && config.agentKey) agentKey = config.agentKey;
+      if (!apiUrl && config.apiUrl) apiUrl = config.apiUrl;
+    } catch {
+      // Config file missing or invalid — that's fine
+    }
+  }
+
+  if (!agentKey) return null;
+
+  return {
+    agentKey,
+    apiUrl: (apiUrl || "https://exovault.co").replace(/\/+$/, ""),
+  };
+}
+
+/**
+ * Extract content from hook input based on role.
+ * Returns null if content should be skipped.
+ */
+function extractContent(input, role) {
+  if (role === "user") {
+    return input.prompt || null;
+  }
+
+  if (role === "assistant") {
+    // Skip re-entry: stop_hook_active means Stop hook already fired
+    if (input.stop_hook_active) return null;
+    return input.last_assistant_message || null;
+  }
+
+  return null;
+}
+
+/**
+ * Prepare the ingest-turn request body.
+ */
+function buildRequestBody(content, role, sessionId) {
+  // Truncate oversized content
+  let trimmed = content;
+  if (trimmed.length > MAX_CONTENT_LENGTH) {
+    trimmed = trimmed.slice(0, MAX_CONTENT_LENGTH) + "\n[truncated]";
+  }
+
+  const body = {
+    content: trimmed,
+    role,
+    agentId: "claude_code",
+  };
+
+  if (sessionId) {
+    body.agentRunId = sessionId;
+  }
+
+  return body;
+}
+
+/**
+ * POST a turn to the ExoVault ingest-turn API.
+ */
+async function postTurn(apiUrl, agentKey, body) {
+  const controller = new AbortController();
+  const timeout = setTimeout(() => controller.abort(), FETCH_TIMEOUT_MS);
+
+  try {
+    await fetch(`${apiUrl}/api/agent/ingest-turn`, {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json",
+        Authorization: `Bearer ${agentKey}`,
+      },
+      body: JSON.stringify(body),
+      signal: controller.signal,
+    });
+  } finally {
+    clearTimeout(timeout);
+  }
+}
+
+/**
+ * Main entry point — reads stdin, extracts content, POSTs to API.
+ */
+async function main() {
+  const role = process.argv[2];
+  if (role !== "user" && role !== "assistant") {
+    process.exit(0);
+  }
+
+  const config = resolveConfig();
+  if (!config) {
+    process.exit(0); // Not configured — silently skip
+  }
+
+  // Read JSON from stdin
+  let data = "";
+  process.stdin.setEncoding("utf8");
+
+  await new Promise((resolve) => {
+    process.stdin.on("data", (chunk) => (data += chunk));
+    process.stdin.on("end", resolve);
+  });
+
+  const input = JSON.parse(data);
+  const content = extractContent(input, role);
+
+  if (!content || content.length < MIN_CONTENT_LENGTH) {
+    process.exit(0); // Too short or empty — skip
+  }
+
+  const body = buildRequestBody(content, role, input.session_id);
+  await postTurn(config.apiUrl, config.agentKey, body);
+}
+
+// Export for testing, execute when run directly
+if (typeof module !== "undefined") {
+  module.exports = {
+    extractContent,
+    buildRequestBody,
+    postTurn,
+    resolveConfig,
+    MAX_CONTENT_LENGTH,
+    MIN_CONTENT_LENGTH,
+    FETCH_TIMEOUT_MS,
+    CONFIG_PATH,
+  };
+}
+
+if (require.main === module) {
+  main().then(
+    () => process.exit(0),
+    () => process.exit(0), // Silently swallow all errors
+  );
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "exovault-mcp-server",
-  "version": "1.0.2",
+  "version": "1.1.1",
   "type": "module",
   "description": "MCP server for ExoVault — read, search, and manage encrypted notes from Claude Code",
   "main": "dist/index.js",
@@ -9,6 +9,7 @@
   },
   "files": [
     "dist/",
+    "hooks/",
     "README.md",
     "LICENSE"
   ],