exovault-mcp-server 1.1.0 → 1.2.0

package/dist/db.d.ts

@@ -191,6 +191,22 @@ export declare function matchNotesByBlindTokens(supabase: SupabaseClient, tokenH
 export declare function getNotesByIds(supabase: SupabaseClient, userId: string, noteIds: string[]): Promise<NoteRow[]>;
 export declare function getNoteByImportSource(supabase: SupabaseClient, userId: string, vaultId: string, importSource: string, importSourceId: string): Promise<NoteRow | null>;
 export declare function getMemoriesByIds(supabase: SupabaseClient, userId: string, memoryIds: string[]): Promise<MemoryRow[]>;
+export interface MediaAttachmentRow {
+    id: string;
+    memory_id: string | null;
+    note_id: string | null;
+    modality: string;
+    mime_type: string;
+    file_name: string | null;
+    file_size_bytes: number;
+    embedding_status: string;
+    extracted_text: string | null;
+    extracted_text_iv: string | null;
+    extraction_status: string;
+}
+export declare function getAttachmentsForMemories(supabase: SupabaseClient, userId: string, memoryIds: string[]): Promise<MediaAttachmentRow[]>;
+export declare function getAttachmentsForNotes(supabase: SupabaseClient, userId: string, noteIds: string[]): Promise<MediaAttachmentRow[]>;
+export declare function formatAttachmentWithExtraction(att: MediaAttachmentRow, decryptedText: string | null, truncate?: number): string;
 export interface ActiveAgentRow {
     agentId: string;
     modelId: string | null;

package/dist/db.js

@@ -372,6 +372,40 @@ export async function getMemoriesByIds(supabase, userId, memoryIds) {
         throw new Error(sanitizeDbError("fetch memories by IDs", error.message));
     return (data ?? []);
 }
+export async function getAttachmentsForMemories(supabase, userId, memoryIds) {
+    if (memoryIds.length === 0)
+        return [];
+    const { data, error } = await supabase
+        .from("media_attachments")
+        .select("id, memory_id, note_id, modality, mime_type, file_name, file_size_bytes, embedding_status, extracted_text, extracted_text_iv, extraction_status")
+        .eq("user_id", userId)
+        .in("memory_id", memoryIds);
+    if (error)
+        throw new Error(sanitizeDbError("fetch attachments", error.message));
+    return (data ?? []);
+}
+export async function getAttachmentsForNotes(supabase, userId, noteIds) {
+    if (noteIds.length === 0)
+        return [];
+    const { data, error } = await supabase
+        .from("media_attachments")
+        .select("id, memory_id, note_id, modality, mime_type, file_name, file_size_bytes, embedding_status, extracted_text, extracted_text_iv, extraction_status")
+        .eq("user_id", userId)
+        .in("note_id", noteIds);
+    if (error)
+        throw new Error(sanitizeDbError("fetch note attachments", error.message));
+    return (data ?? []);
+}
+export function formatAttachmentWithExtraction(att, decryptedText, truncate) {
+    let text = decryptedText;
+    if (text && truncate)
+        text = text.slice(0, truncate);
+    return [
+        `[${att.modality}] ${att.file_name ?? "unnamed"} (${att.mime_type}, ${att.file_size_bytes}B)`,
+        `  embedding: ${att.embedding_status}, extraction: ${att.extraction_status}`,
+        text ? `  content: ${text}` : null,
+    ].filter(Boolean).join("\n");
+}
 export async function getActiveAgents(supabase, userId, sinceDays = 30, limit = 20) {
     const since = new Date();
     since.setDate(since.getDate() - sinceDays);

package/dist/embedding-config.d.ts

@@ -1,11 +1,10 @@
 import type { McpContext } from "./auth.js";
 export interface EmbeddingConfig {
     apiKey: string;
-    baseUrl: string;
     model: string;
 }
 /**
  * Resolve embedding API configuration from env vars or MCP context.
- * Priority: env vars > ctx.openaiApiKey > null.
+ * Priority: env vars > ctx.geminiApiKey > ctx.openaiApiKey > null.
  */
 export declare function resolveEmbeddingConfig(ctx: McpContext): EmbeddingConfig | null;

package/dist/embedding-config.js

@@ -1,23 +1,24 @@
-const OPENAI_EMBEDDING_MODEL = "text-embedding-3-small";
+const DEFAULT_EMBEDDING_MODEL = "gemini-embedding-2-preview";
 /**
  * Resolve embedding API configuration from env vars or MCP context.
- * Priority: env vars > ctx.openaiApiKey > null.
+ * Priority: env vars > ctx.geminiApiKey > ctx.openaiApiKey > null.
  */
 export function resolveEmbeddingConfig(ctx) {
-    const envApiKey = process.env.EMBEDDING_API_KEY ??
-        process.env.OPENAI_API_KEY;
+    const envApiKey = process.env.EXO_GEMINI_KEY ??
+        process.env.GEMINI_API_KEY ??
+        process.env.EMBEDDING_API_KEY;
     if (envApiKey) {
         return {
             apiKey: envApiKey,
-            baseUrl: process.env.EMBEDDING_BASE_URL ?? "https://api.openai.com/v1",
-            model: process.env.EMBEDDING_MODEL ?? OPENAI_EMBEDDING_MODEL,
+            model: process.env.EMBEDDING_MODEL ?? DEFAULT_EMBEDDING_MODEL,
         };
     }
-    if (ctx.openaiApiKey) {
+    // Fallback to MCP context keys
+    const ctxKey = ctx.geminiApiKey ?? ctx.openaiApiKey;
+    if (ctxKey && typeof ctxKey === "string") {
         return {
-            apiKey: ctx.openaiApiKey,
-            baseUrl: "https://api.openai.com/v1",
-            model: OPENAI_EMBEDDING_MODEL,
+            apiKey: ctxKey,
+            model: DEFAULT_EMBEDDING_MODEL,
         };
     }
     return null;

package/dist/extraction-prompt.js

@@ -74,10 +74,10 @@ function truncate(s, max) {
         return undefined;
     return s.length > max ? s.slice(0, max) : s;
 }
-const EXTRACTION_INSTRUCTIONS = `Extract durable knowledge from the activity log above. Return a JSON array, max 8 items.
-Each item uses short keys: {c: content, t: type, i: importance(1-5), e: [entities], s: summary}
-Types: fact, skill, preference, constraint, task
-Only extract knowledge NOT already saved. Skip ephemeral info.
+const EXTRACTION_INSTRUCTIONS = `Extract durable knowledge from the activity log above. Return a JSON array, max 8 items.
+Each item uses short keys: {c: content, t: type, i: importance(1-5), e: [entities], s: summary}
+Types: fact, skill, preference, constraint, task
+Only extract knowledge NOT already saved. Skip ephemeral info.
 Return [] if nothing worth extracting.`;
 // ─── parseExtractionResult ────────────────────────────────────────────
 /**

package/dist/gateway-client.d.ts

@@ -134,8 +134,28 @@ export declare class GatewayClient {
     readNotes(noteIds: string[]): Promise<string>;
     searchNotes(params: {
         query: string;
+        topK?: number;
+        threshold?: number;
+        searchMode?: "auto" | "hybrid" | "bm25" | "semantic";
+        diversity?: number;
         vaultId?: string;
-        limit?: number;
+        includeContent?: boolean;
+        compact?: boolean;
+    }): Promise<string>;
+    search(params: {
+        query: string;
+        topK?: number;
+        threshold?: number;
+        searchMode?: "auto" | "hybrid" | "bm25" | "semantic";
+        diversity?: number;
+        vaultId?: string;
+        includeContent?: boolean;
+        compact?: boolean;
+        scope?: "all" | "memories" | "notes";
+        memoryType?: string;
+        entity?: string;
+        includeArchived?: boolean;
+        decayHalfLife?: number;
     }): Promise<string>;
     createNote(params: {
         vaultId?: string;
@@ -151,17 +171,6 @@ export declare class GatewayClient {
         tags?: string[];
     }): Promise<string>;
     deleteNote(noteId: string): Promise<string>;
-    semanticSearch(params: {
-        query: string;
-        topK?: number;
-        threshold?: number;
-        vaultId?: string;
-    }): Promise<string>;
-    searchAndRead(params: {
-        query: string;
-        maxNotes?: number;
-        vaultId?: string;
-    }): Promise<string>;
     listFolders(params: {
         vaultId?: string;
     }): Promise<string>;
@@ -291,6 +300,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;
@@ -300,4 +319,24 @@ export declare class GatewayClient {
         documentType: "instructions" | "skills" | "checks";
         appendContent: string;
     }): Promise<string>;
+    attachMedia(params: {
+        fileBytes: Uint8Array;
+        fileName: string;
+        mimeType: string;
+        memoryId?: string;
+        vaultId?: string;
+    }): Promise<string>;
+    downloadMedia(params: {
+        attachmentId: string;
+    }): Promise<{
+        attachmentId: string;
+        memoryId: string | null;
+        modality: string;
+        mimeType: string;
+        fileName: string | null;
+        fileSizeBytes: number;
+        embeddingStatus: string;
+        base64Content: string;
+    }>;
+    deleteMedia(attachmentId: string, vaultId?: string): Promise<string>;
 }

package/dist/gateway-client.js

@@ -154,8 +154,12 @@ export class GatewayClient {
         return JSON.stringify(result);
     }
     async searchNotes(params) {
-        const result = await this.request("POST", "/api/agent/search-notes", params);
-        return JSON.stringify(result);
+        const data = await this.request("POST", "/api/agent/search-notes", params);
+        return JSON.stringify(data, null, 2);
+    }
+    async search(params) {
+        const data = await this.request("POST", "/api/agent/search", params);
+        return JSON.stringify(data, null, 2);
     }
     async createNote(params) {
         const result = await this.request("POST", "/api/agent/create-note", params);
@@ -169,14 +173,6 @@ export class GatewayClient {
         const result = await this.request("POST", "/api/agent/delete-note", { noteId });
         return JSON.stringify(result);
     }
-    async semanticSearch(params) {
-        const result = await this.request("POST", "/api/agent/semantic-search", params);
-        return JSON.stringify(result);
-    }
-    async searchAndRead(params) {
-        const result = await this.request("POST", "/api/agent/search-and-read", params);
-        return JSON.stringify(result);
-    }
     // ─── Folder operations ──────────────────────────────────────────────────
     async listFolders(params) {
         const result = await this.request("POST", "/api/agent/list-folders", params);
@@ -274,6 +270,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);
@@ -282,4 +283,51 @@ export class GatewayClient {
         const result = await this.request("POST", "/api/agent/update-document", params);
         return JSON.stringify(result);
     }
+    // ─── Media operations ───────────────────────────────────────────────────────
+    async attachMedia(params) {
+        const url = `${this.baseUrl}/api/agent/attach-media`;
+        const headers = {
+            Authorization: `Bearer ${this.apiKey}`,
+        };
+        if (this.sessionRunId) {
+            headers["X-Agent-Run-Id"] = this.sessionRunId;
+        }
+        // Build multipart form data
+        const formData = new FormData();
+        const ab = params.fileBytes.buffer.slice(params.fileBytes.byteOffset, params.fileBytes.byteOffset + params.fileBytes.byteLength);
+        const blob = new Blob([ab], { type: params.mimeType });
+        formData.append("file", blob, params.fileName);
+        if (params.memoryId)
+            formData.append("memoryId", params.memoryId);
+        if (params.vaultId)
+            formData.append("vaultId", params.vaultId);
+        const response = await fetch(url, {
+            method: "POST",
+            headers,
+            body: formData,
+        });
+        if (!response.ok) {
+            let errorBody;
+            try {
+                errorBody = await response.json();
+            }
+            catch {
+                errorBody = null;
+            }
+            const message = errorBody?.error ?? `Gateway returned ${response.status}`;
+            throw new GatewayError(message, response.status, errorBody);
+        }
+        const result = await response.json();
+        return JSON.stringify(result);
+    }
+    async downloadMedia(params) {
+        return this.request("POST", "/api/agent/download-media", params);
+    }
+    async deleteMedia(attachmentId, vaultId) {
+        const body = { attachmentId };
+        if (vaultId)
+            body.vaultId = vaultId;
+        const res = await this.request("POST", "/api/agent/delete-media", body);
+        return JSON.stringify(res);
+    }
 }

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";
@@ -10,8 +12,6 @@ import { listNotes } from "./tools/list-notes.js";
 import { readNote } from "./tools/read-note.js";
 import { readNotes } from "./tools/read-notes.js";
 import { searchNotes } from "./tools/search-notes.js";
-import { semanticSearch } from "./tools/semantic-search.js";
-import { searchAndRead } from "./tools/search-and-read.js";
 import { createNote } from "./tools/create-note.js";
 import { updateNote } from "./tools/update-note.js";
 import { deleteNote } from "./tools/delete-note.js";
@@ -27,6 +27,8 @@ 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 { search } from "./tools/search.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 +52,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 +86,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 {
@@ -344,7 +370,7 @@ async function main() {
     if (gw) {
         instructionLines.push("Running in gateway mode. Turn ingestion is automatic.");
     }
-    instructionLines.push("", "## Tasks", "`create_task` (title, description, status, priority, assignedAgentId, doneWhen). `update_task` to change status. `list_tasks` to view.", "Set `doneWhen` for auto-detect completion. Tasks are memories with memoryType='task'.", "assignedAgentId: null=unassigned, 'any'=any agent, '<type>'=specific. Check assigned tasks at session start.", "", "## Messages", "Pending messages from users/agents appear in `session_start` and `context_checkpoint` responses under `pendingMessages`.", "**When you receive a message**: respond with `send_message(targetId: 'user', content: '...', parentMessageId: '<message.id>')` to reply in-thread.", "`ack_message(messageId)` to acknowledge without replying. `read_messages(agentId)` to fetch messages on demand.", "", "## Memory Protocol", "1. Scope to vaultId. 2. SEARCH FIRST before writing/answering. 3. externalWriteId for idempotency.", "4. Set importance+confidence (1-5). 5. Extract entities. 6. relatedMemoryIds for links. 7. supersededById for corrections.", "Types: fact, skill, preference, constraint, task, episodic, correction. Always set dedup:true, agentId, agentRunId.", "", "## Retrieval Tools (pick the right one)", "- `search_memories` — hybrid search. Use compact:true, then read_memories for full content.", "- `explore_graph` — **PREFERRED for deep retrieval**. query/nodeId → multi-hop graph map (nodes+edges). Then read_memories/read_note for full content. Zero LLM cost.", "- `semantic_search` — vector similarity across notes+memories.", "- `search_and_read` — search + auto-read in one call.", "- `get_links` / `get_related_memories` — single-hop link traversal.", "- `read_document` — vault docs (instructions, skills, checks).");
+    instructionLines.push("", "## Tasks", "`create_task` (title, description, status, priority, assignedAgentId, doneWhen). `update_task` to change status. `list_tasks` to view.", "Set `doneWhen` for auto-detect completion. Tasks are memories with memoryType='task'.", "assignedAgentId: null=unassigned, 'any'=any agent, '<type>'=specific. Check assigned tasks at session start.", "", "## Messages", "Pending messages from users/agents appear in `session_start` and `context_checkpoint` responses under `pendingMessages`.", "**When you receive a message**: respond with `send_message(targetId: 'user', content: '...', parentMessageId: '<message.id>')` to reply in-thread.", "`ack_message(messageId)` to acknowledge without replying. `read_messages(agentId)` to fetch messages on demand.", "", "## Memory Protocol", "1. Scope to vaultId. 2. SEARCH FIRST before writing/answering. 3. externalWriteId for idempotency.", "4. Set importance+confidence (1-5). 5. Extract entities. 6. relatedMemoryIds for links. 7. supersededById for corrections.", "Types: fact, skill, preference, constraint, task, episodic, correction. Always set dedup:true, agentId, agentRunId.", "", "## Retrieval Tools (pick the right one)", "- `search` — **universal search** across memories+notes with cross-type MMR. Set scope='all' (default), 'memories', or 'notes'.", "- `search_memories` — hybrid search memories only. Use compact:true, then read_memories for full content.", "- `search_notes` — hybrid search notes only. Use includeContent:true for full content, or read_notes for specific IDs.", "- `explore_graph` — **PREFERRED for deep retrieval**. query/nodeId → multi-hop graph map (nodes+edges). Then read_memories/read_note for full content. Zero LLM cost.", "- `get_links` / `get_related_memories` — single-hop link traversal.", "- `read_document` — vault docs (instructions, skills, checks).");
     const instructionsText = instructionLines.join("\n");
     // ── Guard: keep instructions ≤4,000 chars ─────────────────────────
     const INSTRUCTION_CHAR_LIMIT = 4_000;
@@ -411,17 +437,22 @@ async function main() {
     })));
     // ─── search_notes ─────────────────────────────────────────────────────────
     server.registerTool("search_notes", {
-        description: "Search notes by keyword. Weighted: 3x title, 2x tags, 1x content. Returns scored results.",
+        description: "Search notes using 4-signal hybrid scoring (semantic + BM25 + blind index + graph) with RRF fusion and MMR diversity. Gateway mode uses server-side pipeline; direct mode uses local Supabase queries. Use includeContent:true to get full note content inline, or follow up with read_notes for specific IDs. Consider `search` tool (scope='notes') for unified cross-type results.",
         inputSchema: {
-            query: s(z.string().min(1).describe("Search query")),
+            query: s(z.string().min(1).describe("Search query (natural language or keywords)")),
+            topK: s(z.number().int().min(1).max(50).optional().describe("Max results (default 10)")),
+            threshold: s(z.number().min(0).max(1).optional().describe("Minimum similarity threshold 0-1 (default 0.5)")),
+            searchMode: s(z.enum(["auto", "hybrid", "bm25", "semantic"]).optional().describe("Search mode: auto (default), hybrid, bm25, or semantic")),
+            diversity: s(z.number().min(0).max(1).optional().describe("MMR diversity balance 0-1 (default 0.7). Higher = more relevance, lower = more diversity.")),
             vaultId: s(z.string().uuid().optional().describe("Limit search to a specific vault")),
-            limit: s(z.number().int().min(1).max(50).optional().describe("Max results (default 10)")),
+            includeContent: s(z.boolean().optional().describe("Include full note content in results (default false, returns preview only)")),
+            compact: s(z.boolean().optional().describe("Return shorter previews (200 chars instead of 500)")),
         },
     }, auto.wrap(wrapToolHandler(async (args) => {
-        const { query, vaultId, limit } = args;
+        const input = args;
         return gw
-            ? await gw.searchNotes({ query, vaultId: resolveVault(vaultId), limit })
-            : await searchNotes(ctx, query, resolveVaultId(ctx, vaultId), limit);
+            ? await gw.searchNotes({ ...input, vaultId: resolveVault(input.vaultId) })
+            : await searchNotes(ctx, { ...input, vaultId: resolveVaultId(ctx, input.vaultId) });
     })));
     // ─── create_note ──────────────────────────────────────────────────────────
     server.registerTool("create_note", {
@@ -522,35 +553,6 @@ async function main() {
         const { noteIds } = args;
         return gw ? await gw.readNotes(noteIds) : await readNotes(ctx, noteIds);
     })));
-    // ─── semantic_search ────────────────────────────────────────────────────
-    server.registerTool("semantic_search", {
-        description: "Search notes by meaning using vector embeddings. Finds conceptually similar content even without exact keyword matches. Requires OpenAI API key in config.",
-        inputSchema: {
-            query: s(z.string().min(1).describe("Natural language search query")),
-            topK: s(z.number().int().min(1).max(50).optional().describe("Max results (default 10)")),
-            threshold: s(z.number().min(0).max(1).optional().describe("Minimum similarity threshold 0-1 (default 0.5)")),
-            vaultId: s(z.string().uuid().optional().describe("Vault to search within. Uses default vault if omitted.")),
-        },
-    }, auto.wrap(wrapToolHandler(async (args) => {
-        const { query, topK, threshold, vaultId } = args;
-        return gw
-            ? await gw.semanticSearch({ query, topK, threshold, vaultId: resolveVault(vaultId) })
-            : await semanticSearch(ctx, query, topK, threshold);
-    })));
-    // ─── search_and_read ────────────────────────────────────────────────────
-    server.registerTool("search_and_read", {
-        description: "Search notes using hybrid scoring (70% semantic + 30% keyword) and return the full content of top matches. Falls back to keyword-only if no OpenAI key, and to recency if no matches found. Best for gathering all relevant content on a topic.",
-        inputSchema: {
-            query: s(z.string().min(1).describe("Search query (natural language or keywords)")),
-            maxNotes: s(z.number().int().min(1).max(20).optional().describe("Max notes to return (default 5)")),
-            vaultId: s(z.string().uuid().optional().describe("Vault to search within. Uses default vault if omitted.")),
-        },
-    }, auto.wrap(wrapToolHandler(async (args) => {
-        const { query, maxNotes, vaultId } = args;
-        return gw
-            ? await gw.searchAndRead({ query, maxNotes, vaultId: resolveVault(vaultId) })
-            : await searchAndRead(ctx, query, maxNotes);
-    })));
     // ─── write_memory ───────────────────────────────────────────────────────────
     server.registerTool("write_memory", {
         description: "Create or upsert a durable memory entry.\n\nMemory types: fact (durable knowledge, importance 3-5), skill (procedures/how-tos, 3-5), preference (user style/choices, 2-4), constraint (hard rules/limits, 4-5), task (active work items, 2-4), episodic (session summaries, 1-3), correction (superseded knowledge — always set supersededById, 3-5).\n\nImportance scale: 5=critical, 4=important, 3=standard (default), 2=supplementary, 1=low-value. Confidence scale: 5=verified, 4=observed multiple times, 3=reasonable inference (default), 2=uncertain, 1=speculative.\n\nRelationship fields: relatedMemoryIds links to related memories (derived_from, contradicts, refines, part_of, supersedes). sourceNoteIds links to source notes. supersededById points to the memory this one replaces. entities array enables cross-linking.\n\nServer dedup (dedup: true): >92% similarity = skip, >80% = supersede old, <80% = create new.",
@@ -611,6 +613,31 @@ async function main() {
         }
         return await searchMemories(ctx, { ...input, vaultId: resolveVaultId(ctx, input.vaultId) });
     })));
+    // ─── search (universal) ─────────────────────────────────────────────────────
+    server.registerTool("search", {
+        description: "Universal search across both memories and notes. Set scope to 'all' (default) for cross-type MMR-ranked results, 'memories' for memories only, or 'notes' for notes only. In gateway mode, delegates to the server for full cross-type MMR re-ranking. In direct mode, best-effort interleave.",
+        inputSchema: {
+            query: s(z.string().min(1).describe("Natural language search query")),
+            topK: s(z.number().int().min(1).max(50).optional().describe("Max results (default 10)")),
+            threshold: s(z.number().min(0).max(1).optional().describe("Similarity threshold 0-1 (default 0.5)")),
+            searchMode: s(z.enum(["auto", "hybrid", "bm25", "semantic"]).optional().describe("Search mode (default: auto)")),
+            diversity: s(z.number().min(0).max(1).optional().describe("MMR diversity balance 0-1 (default 0.7)")),
+            vaultId: s(z.string().uuid().optional().describe("Vault filter")),
+            includeContent: s(z.boolean().optional().describe("Include full note content (default false)")),
+            compact: s(z.boolean().optional().describe("Return shorter previews")),
+            scope: s(z.enum(["all", "memories", "notes"]).optional().describe("Search scope: all (default), memories, or notes")),
+            memoryType: s(z.string().optional().describe("Filter by memory type (memories scope only)")),
+            entity: s(z.string().optional().describe("Search by entity name (memories scope only)")),
+            includeArchived: s(z.boolean().optional().describe("Include archived memories (default false)")),
+            decayHalfLife: s(z.number().int().min(1).max(365).optional().describe("Temporal decay half-life in days (default 30)")),
+        },
+    }, auto.wrap(wrapToolHandler(async (args) => {
+        const input = args;
+        if (gw) {
+            return await gw.search({ ...input, vaultId: resolveVault(input.vaultId) });
+        }
+        return await search(ctx, { ...input, vaultId: resolveVaultId(ctx, input.vaultId) });
+    })));
     // ─── read_memories ──────────────────────────────────────────────────────────
     server.registerTool("read_memories", {
         description: "Read and decrypt full memory entries by IDs.",
@@ -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,81 @@ 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) });
+    })));
+    // ─── attach_media ──────────────────────────────────────────────────────────
+    server.registerTool("attach_media", {
+        description: "Attach a media file (image, PDF, audio, video) to a memory for multimodal embedding. The file is encrypted at rest and embedded via Gemini for cross-modal search. Accepts base64-encoded file content.\n\nSupported types: images (PNG, JPEG, WebP, GIF — 20MB), documents (PDF — 50MB), audio (MP3, WAV, OGG, WebM — 50MB), video (MP4, WebM, QuickTime — 20MB). SVG is not supported.\n\nPer-user storage quota applies (free tier: 100MB).",
+        inputSchema: {
+            fileBase64: s(z.string().min(1).describe("Base64-encoded file content")),
+            fileName: s(z.string().min(1).describe("Original file name with extension")),
+            mimeType: s(z.string().min(1).describe("MIME type (e.g. image/png, application/pdf, audio/mpeg, video/mp4)")),
+            memoryId: s(z.string().uuid().optional().describe("Memory to attach this media to")),
+            vaultId: s(z.string().uuid().optional().describe("Vault scope")),
+        },
+    }, auto.wrap(wrapToolHandler(async (args) => {
+        const input = args;
+        if (!gw)
+            throw new Error("attach_media requires gateway mode (agent key)");
+        const fileBytes = Buffer.from(input.fileBase64, "base64");
+        return await gw.attachMedia({
+            fileBytes: new Uint8Array(fileBytes),
+            fileName: input.fileName,
+            mimeType: input.mimeType,
+            memoryId: input.memoryId,
+            vaultId: resolveVault(input.vaultId),
+        });
+    })));
+    // ─── download_media ───────────────────────────────────────────────────────
+    server.registerTool("download_media", {
+        description: "Download and decrypt a media attachment by ID. Returns base64-encoded file content with metadata.",
+        inputSchema: {
+            attachmentId: s(z.string().uuid().describe("Media attachment ID to download")),
+        },
+    }, auto.wrap(wrapToolHandler(async (args) => {
+        const { attachmentId } = args;
+        if (!gw)
+            throw new Error("download_media requires gateway mode (agent key)");
+        const result = await gw.downloadMedia({ attachmentId });
+        return JSON.stringify(result);
+    })));
+    // ─── delete_media ───────────────────────────────────────────────────────
+    server.registerTool("delete_media", {
+        description: "Delete a media attachment and its embedding. Permanently removes the file from storage.",
+        inputSchema: {
+            attachmentId: s(z.string().uuid().describe("The attachment ID to delete")),
+            vaultId: s(z.string().uuid().optional().describe("Optional vault scope")),
+        },
+    }, auto.wrap(wrapToolHandler(async (args) => {
+        const { attachmentId, vaultId } = args;
+        if (!gw)
+            throw new Error("delete_media requires gateway mode (agent key)");
+        return await gw.deleteMedia(attachmentId, vaultId);
+    })));
     // ─── Orphan recovery — flush crashed sessions from previous runs ─────────
     try {
         const orphans = await scanOrphanedBuffers(10);

package/dist/openai.d.ts

@@ -1,12 +1,14 @@
 /**
- * Generates one query embedding using OpenAI text-embedding-3-small.
+ * Generates one query embedding using Gemini.
+ * Used in direct mode for semantic search queries.
  */
 export declare function generateQueryEmbedding(text: string, apiKey: string, options?: {
     model?: string;
     baseUrl?: string;
 }): Promise<number[]>;
 /**
- * Generates multiple embeddings in one request when possible.
+ * Generates multiple embeddings in one request.
+ * Used in direct mode for bulk embedding operations.
  */
 export declare function generateEmbeddings(values: string[], apiKey: string, options?: {
     model?: string;