exovault-mcp-server 1.3.0 → 1.4.1

package/dist/db.d.ts

@@ -97,6 +97,8 @@ export declare function getMemories(supabase: SupabaseClient, userId: string, op
     includeArchived?: boolean;
     limit?: number;
     orderBy?: "updated_at" | "importance";
+    /** Use lightweight columns (no encrypted content/summary). Default: false. */
+    lightweight?: boolean;
 }): Promise<MemoryRow[]>;
 export declare function getMemory(supabase: SupabaseClient, userId: string, memoryId: string): Promise<MemoryRow | null>;
 export declare function getMemoryByExternalWriteId(supabase: SupabaseClient, userId: string, externalWriteId: string): Promise<MemoryRow | null>;

package/dist/db.js

@@ -1,9 +1,14 @@
 import { sanitizeDbError } from "./error-sanitizer.js";
+// ─── Column lists (explicit to avoid SELECT * egress overhead) ───────────────
+const VAULT_COLUMNS = "id, user_id, encrypted_name, name_iv, icon, color, sort_order, created_at, updated_at";
+const NOTE_COLUMNS = "id, user_id, vault_id, encrypted_title, title_iv, encrypted_content, content_iv, content_type, encrypted_tags, tags_iv, embedding_status, import_source, import_source_id, is_trashed, created_at, updated_at";
+const LINK_COLUMNS = "id, user_id, source_type, source_id, target_type, target_id, relation_type, encrypted_label, label_iv, is_pending, pending_target_hash, created_at, created_by";
+const MESSAGE_COLUMNS = "id, user_id, vault_id, sender_type, sender_id, target_type, target_id, category, priority, subject, encrypted_content, content_iv, status, delivered_at, acknowledged_at, parent_message_id, thread_id, expires_at, metadata, created_at, updated_at";
 // ─── Query helpers ────────────────────────────────────────────────────────────
 export async function getVaults(supabase, userId) {
     const { data, error } = await supabase
         .from("vaults")
-        .select("*")
+        .select(VAULT_COLUMNS)
         .eq("user_id", userId)
         .order("sort_order", { ascending: true });
     if (error)
@@ -13,7 +18,7 @@ export async function getVaults(supabase, userId) {
 export async function getNotes(supabase, userId, vaultId, limit = 20) {
     let query = supabase
         .from("notes")
-        .select("*")
+        .select(NOTE_COLUMNS)
         .eq("user_id", userId)
         .eq("is_trashed", false)
         .order("updated_at", { ascending: false })
@@ -29,7 +34,7 @@ export async function getNotes(supabase, userId, vaultId, limit = 20) {
 export async function getNote(supabase, userId, noteId) {
     const { data, error } = await supabase
         .from("notes")
-        .select("*")
+        .select(NOTE_COLUMNS)
         .eq("id", noteId)
         .eq("user_id", userId)
         .single();
@@ -43,7 +48,7 @@ export async function getNote(supabase, userId, noteId) {
 export async function getVault(supabase, userId, vaultId) {
     const { data, error } = await supabase
         .from("vaults")
-        .select("*")
+        .select(VAULT_COLUMNS)
         .eq("id", vaultId)
         .eq("user_id", userId)
         .single();
@@ -102,9 +107,15 @@ export async function getMemories(supabase, userId, options) {
     const includeArchived = options?.includeArchived ?? false;
     const limit = options?.limit ?? 50;
     const orderBy = options?.orderBy ?? "updated_at";
+    // Lightweight mode: select only metadata columns (no encrypted content/summary) to reduce egress.
+    // Supabase's TS type parser can't handle long literal strings, so we build the query separately.
+    const columns = options?.lightweight
+        ? "id,user_id,vault_id,memory_type,agent_id,agent_type,model_id,agent_run_id,importance,confidence,access_count,is_archived,entities,superseded_by_id,created_at,updated_at"
+        : "*";
     let query = supabase
         .from("memories")
-        .select("*")
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        .select(columns)
         .eq("user_id", userId)
         .order(orderBy, { ascending: false })
         .limit(limit);
@@ -339,7 +350,7 @@ export async function getNotesByIds(supabase, userId, noteIds) {
         return [];
     const { data, error } = await supabase
         .from("notes")
-        .select("*")
+        .select(NOTE_COLUMNS)
         .eq("user_id", userId)
         .eq("is_trashed", false)
         .in("id", noteIds);
@@ -350,7 +361,7 @@ export async function getNotesByIds(supabase, userId, noteIds) {
 export async function getNoteByImportSource(supabase, userId, vaultId, importSource, importSourceId) {
     const { data, error } = await supabase
         .from("notes")
-        .select("*")
+        .select(NOTE_COLUMNS)
         .eq("user_id", userId)
         .eq("vault_id", vaultId)
         .eq("import_source", importSource)
@@ -583,7 +594,7 @@ export async function insertKnowledgeLink(supabase, data) {
         pending_target_hash: data.pending_target_hash ?? null,
         created_by: data.created_by ?? null,
     })
-        .select()
+        .select(LINK_COLUMNS)
         .single();
     if (error)
         throw new Error(sanitizeDbError("insert knowledge link", error.message));
@@ -604,7 +615,7 @@ export async function getLinksForNode(supabase, userId, nodeType, nodeId, option
     if (direction === "outgoing") {
         const { data, error } = await supabase
             .from("knowledge_links")
-            .select()
+            .select(LINK_COLUMNS)
             .eq("user_id", userId)
             .eq("source_type", nodeType)
             .eq("source_id", nodeId)
@@ -617,7 +628,7 @@ export async function getLinksForNode(supabase, userId, nodeType, nodeId, option
     if (direction === "incoming") {
         const { data, error } = await supabase
             .from("knowledge_links")
-            .select()
+            .select(LINK_COLUMNS)
             .eq("user_id", userId)
             .eq("target_type", nodeType)
             .eq("target_id", nodeId)
@@ -631,7 +642,7 @@ export async function getLinksForNode(supabase, userId, nodeType, nodeId, option
     const [outgoing, incoming] = await Promise.all([
         supabase
             .from("knowledge_links")
-            .select()
+            .select(LINK_COLUMNS)
             .eq("user_id", userId)
             .eq("source_type", nodeType)
             .eq("source_id", nodeId)
@@ -639,7 +650,7 @@ export async function getLinksForNode(supabase, userId, nodeType, nodeId, option
             .limit(limit),
         supabase
             .from("knowledge_links")
-            .select()
+            .select(LINK_COLUMNS)
             .eq("user_id", userId)
             .eq("target_type", nodeType)
             .eq("target_id", nodeId)
@@ -724,7 +735,7 @@ export async function resolvePendingLinks(supabase, userId, hashToNoteId) {
     // Fetch all pending links for this user
     const { data: pending, error } = await supabase
         .from("knowledge_links")
-        .select()
+        .select(LINK_COLUMNS)
         .eq("user_id", userId)
         .eq("is_pending", true)
         .limit(10_000);
@@ -786,7 +797,7 @@ export async function insertAgentMessage(supabase, data) {
         parent_message_id: data.parent_message_id ?? null,
         thread_id: data.thread_id ?? null,
     })
-        .select("*")
+        .select(MESSAGE_COLUMNS)
         .single();
     if (error)
         throw new Error(sanitizeDbError("insert agent message", error.message));
@@ -799,7 +810,7 @@ export async function insertAgentMessage(supabase, data) {
 export async function getPendingMessages(supabase, userId, targetId, limit = 5) {
     const { data, error } = await supabase
         .from("agent_messages")
-        .select("*")
+        .select(MESSAGE_COLUMNS)
         .eq("user_id", userId)
         .eq("status", "pending")
         .or(`target_id.eq.${targetId},target_id.eq.*`)
@@ -819,7 +830,7 @@ export async function getAgentMessages(supabase, userId, targetId, options) {
     const includeBroadcast = options?.includeBroadcast ?? true;
     let query = supabase
         .from("agent_messages")
-        .select("*")
+        .select(MESSAGE_COLUMNS)
         .eq("user_id", userId)
         .order("priority", { ascending: false })
         .order("created_at", { ascending: false })
@@ -890,7 +901,7 @@ export async function resolveThreadId(supabase, userId, parentMessageId) {
 export async function getThread(supabase, userId, threadId) {
     const { data, error } = await supabase
         .from("agent_messages")
-        .select("*")
+        .select(MESSAGE_COLUMNS)
         .eq("user_id", userId)
         .eq("thread_id", threadId)
         .order("created_at", { ascending: true });

package/dist/embedding-config.js

@@ -10,7 +10,7 @@ export function resolveEmbeddingConfig(ctx) {
     if (envApiKey) {
         return {
             apiKey: envApiKey,
-            model: process.env.EMBEDDING_MODEL ?? DEFAULT_EMBEDDING_MODEL,
+            model: DEFAULT_EMBEDDING_MODEL, // Hardcoded — EMBEDDING_MODEL is for OpenAI text
         };
     }
     // Fallback to MCP context keys

package/dist/episodic-headline.d.ts

@@ -1,6 +1,9 @@
 /**
  * Extracts a short headline (max 200 chars) from episodic memory content.
- * Strips the "Session: Xm, agent=Y." metadata prefix and returns the
- * first 1-2 substantive sentences. Pure function, no LLM calls.
+ *
+ * New format: first line is the session title, followed by details.
+ * Legacy format: "Session: Xm, agent=Y." prefix is stripped.
+ *
+ * Pure function, no LLM calls.
  */
 export declare function generateEpisodicHeadline(content: string): string;

package/dist/episodic-headline.js

@@ -1,21 +1,30 @@
 /**
  * Extracts a short headline (max 200 chars) from episodic memory content.
- * Strips the "Session: Xm, agent=Y." metadata prefix and returns the
- * first 1-2 substantive sentences. Pure function, no LLM calls.
+ *
+ * New format: first line is the session title, followed by details.
+ * Legacy format: "Session: Xm, agent=Y." prefix is stripped.
+ *
+ * Pure function, no LLM calls.
  */
 const MAX_HEADLINE_CHARS = 200;
-// Matches "Session: <duration>, agent=<name>." prefix (with optional newlines after)
+// Legacy prefix — matches "Session: <duration>, agent=<name>." (with optional newlines after)
 const SESSION_PREFIX_RE = /^Session:\s*\S+,\s*agent=\S+\.\s*/;
 export function generateEpisodicHeadline(content) {
     if (!content)
         return "";
-    // Strip the metadata prefix
+    // Strip legacy metadata prefix if present
     const body = content.replace(SESSION_PREFIX_RE, "").trim();
     // If stripping left nothing, return original content
     if (!body)
         return content;
-    // For rule-based format ("Explored: ...\nOutcomes: ..."), join lines
-    // For LLM narrative, take first 1-2 sentences
+    // First line is the session title — use it as headline if it fits
+    const firstLineEnd = body.indexOf("\n");
+    const firstLine = firstLineEnd > 0 ? body.slice(0, firstLineEnd).trim() : body.trim();
+    // If first line is short enough and not a "Explored:/Outcomes:" detail line, use it directly
+    if (firstLine.length <= MAX_HEADLINE_CHARS && !firstLine.startsWith("Explored:") && !firstLine.startsWith("Outcomes:")) {
+        return firstLine;
+    }
+    // Fallback: take first 1-2 sentences from body
     const sentences = splitIntoSentences(body);
     // Take enough sentences to fill ~200 chars
     let headline = "";
@@ -24,7 +33,6 @@ export function generateEpisodicHeadline(content) {
             continue;
         const candidate = headline ? `${headline} ${sentence}` : sentence;
         if (candidate.length > MAX_HEADLINE_CHARS) {
-            // If we have nothing yet, take this sentence (will be clipped)
             if (!headline)
                 headline = sentence;
             break;

package/dist/gateway-client.d.ts

@@ -69,7 +69,7 @@ export declare class GatewayClient {
         graphSeeds?: number;
         graphMaxHops?: number;
     }): Promise<string>;
-    readMemories(memoryIds: string[]): Promise<string>;
+    readMemories(memoryIds: string[], includeMediaContent?: boolean): Promise<string>;
     updateMemory(params: {
         memoryId: string;
         content?: string;
@@ -136,8 +136,8 @@ export declare class GatewayClient {
         limit?: number;
         folderId?: string;
     }): Promise<string>;
-    readNote(noteId: string): Promise<string>;
-    readNotes(noteIds: string[]): Promise<string>;
+    readNote(noteId: string, includeMediaContent?: boolean): Promise<string>;
+    readNotes(noteIds: string[], includeMediaContent?: boolean): Promise<string>;
     searchNotes(params: {
         query: string;
         topK?: number;
@@ -195,6 +195,10 @@ export declare class GatewayClient {
         icon?: string;
         color?: string;
     }): Promise<string>;
+    deleteVault(params: {
+        vaultId: string;
+        confirm: true;
+    }): Promise<string>;
     createTask(params: {
         title: string;
         description?: string;
@@ -344,5 +348,21 @@ export declare class GatewayClient {
         embeddingStatus: string;
         base64Content: string;
     }>;
+    viewMedia(params: {
+        attachmentId: string;
+    }): Promise<{
+        attachmentId: string;
+        memoryId: string | null;
+        noteId: string | null;
+        modality: string;
+        mimeType: string;
+        fileName: string | null;
+        fileSizeBytes: number;
+        embeddingStatus: string;
+        extractionStatus: string;
+        extractedText: string | null;
+        base64Content: string | null;
+        contentNote: string | null;
+    }>;
     deleteMedia(attachmentId: string, vaultId?: string): Promise<string>;
 }

package/dist/gateway-client.js

@@ -102,8 +102,8 @@ export class GatewayClient {
         const result = await this.request("POST", "/api/agent/search-memories", params);
         return JSON.stringify(result);
     }
-    async readMemories(memoryIds) {
-        const result = await this.request("POST", "/api/agent/read-memories", { memoryIds });
+    async readMemories(memoryIds, includeMediaContent) {
+        const result = await this.request("POST", "/api/agent/read-memories", { memoryIds, includeMediaContent });
         return JSON.stringify(result);
     }
     async updateMemory(params) {
@@ -145,12 +145,12 @@ export class GatewayClient {
         const result = await this.request("POST", "/api/agent/list-notes", params);
         return JSON.stringify(result);
     }
-    async readNote(noteId) {
-        const result = await this.request("POST", "/api/agent/read-note", { noteId });
+    async readNote(noteId, includeMediaContent) {
+        const result = await this.request("POST", "/api/agent/read-note", { noteId, includeMediaContent });
         return JSON.stringify(result);
     }
-    async readNotes(noteIds) {
-        const result = await this.request("POST", "/api/agent/read-notes", { noteIds });
+    async readNotes(noteIds, includeMediaContent) {
+        const result = await this.request("POST", "/api/agent/read-notes", { noteIds, includeMediaContent });
         return JSON.stringify(result);
     }
     async searchNotes(params) {
@@ -191,6 +191,10 @@ export class GatewayClient {
         const result = await this.request("POST", "/api/agent/create-vault", params);
         return JSON.stringify(result);
     }
+    async deleteVault(params) {
+        const result = await this.request("POST", "/api/agent/delete-vault", params);
+        return JSON.stringify(result);
+    }
     // ─── Task operations ─────────────────────────────────────────────────────
     async createTask(params) {
         const result = await this.request("POST", "/api/agent/create-task", params);
@@ -323,6 +327,9 @@ export class GatewayClient {
     async downloadMedia(params) {
         return this.request("POST", "/api/agent/download-media", params);
     }
+    async viewMedia(params) {
+        return this.request("POST", "/api/agent/view-media", params);
+    }
     async deleteMedia(attachmentId, vaultId) {
         const body = { attachmentId };
         if (vaultId)

package/dist/index.js

@@ -30,6 +30,7 @@ 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";
+import { viewMedia } from "./tools/view-media.js";
 // Task tools are thin wrappers around memory tools — no separate agent-tasks import needed
 import { resolveVaultId } from "./tools/resolve-vault-id.js";
 import { GatewayClient } from "./gateway-client.js";
@@ -48,7 +49,7 @@ import { scanOrphanedBuffers, deleteBuffer as deleteBufferFile } from "./buffer-
 import { flushSession } from "./session-flush.js";
 import { coerceSchema } from "./coerce-params.js";
 const s = (schema) => coerceSchema(schema);
-const MEMORY_TYPES = ["fact", "skill", "preference", "constraint", "task", "episodic", "correction"];
+const MEMORY_TYPES = ["fact", "skill", "preference", "constraint", "task", "episodic", "correction", "decision"];
 const memoryTypeEnum = z.enum(MEMORY_TYPES);
 /** Remind agents to checkpoint every N tool calls. */
 const CHECKPOINT_REMINDER_INTERVAL = 20;
@@ -351,7 +352,7 @@ async function main() {
         "   b. **WRITE on these triggers** — call `write_memory` IMMEDIATELY when:",
         "      - User states a preference, rule, or convention → `preference` or `constraint`",
         "      - You discover a non-obvious fact about the domain/project/topic → `fact` (importance 3-5)",
-        "      - A decision is made (by user or jointly) → `fact` (importance 4-5)",
+        "      - A decision is made (by user or jointly) → `decision` (importance 4-5, include inputs, reasoning, alternatives, outcome)",
         "      - You solve a problem or learn a procedure → `skill`",
         "      - You hit a surprising gotcha or limitation → `skill` (importance 4)",
         "      - Previous knowledge turns out wrong → `correction` (set supersededById)",
@@ -411,6 +412,20 @@ async function main() {
             ? await gw.createVault({ name, icon, color })
             : await createVault(ctx, name, { icon, color });
     })));
+    // ─── delete_vault ──────────────────────────────────────────────────────────
+    server.registerTool("delete_vault", {
+        description: "Permanently delete a vault and all its notes/folders. Memories are preserved (vault_id set to null). Requires admin scope and confirm: true. Cannot delete the default vault.",
+        inputSchema: {
+            vaultId: s(z.string().uuid().describe("The vault ID to delete")),
+            confirm: s(z.literal(true).describe("Must be true to confirm deletion")),
+        },
+    }, auto.wrap(wrapToolHandler(async (args) => {
+        const { vaultId, confirm } = args;
+        if (!gw) {
+            return JSON.stringify({ success: false, error: "delete_vault requires gateway mode" });
+        }
+        return await gw.deleteVault({ vaultId, confirm });
+    })));
     // ─── list_notes ───────────────────────────────────────────────────────────
     server.registerTool("list_notes", {
         description: "List notes with titles, tags, and content previews. Optionally filter by vault or folder.",
@@ -430,10 +445,11 @@ async function main() {
         description: "Read the full decrypted content of a note, including title, tags, and vault name",
         inputSchema: {
             noteId: s(z.string().uuid().describe("The note ID to read")),
+            includeMediaContent: s(z.boolean().optional().describe("When true, includes base64 image content for images under 500KB. Gateway mode only. Default: false.")),
         },
     }, auto.wrap(wrapToolHandler(async (args) => {
-        const { noteId } = args;
-        return gw ? await gw.readNote(noteId) : await readNote(ctx, noteId);
+        const { noteId, includeMediaContent } = args;
+        return gw ? await gw.readNote(noteId, includeMediaContent) : await readNote(ctx, noteId, includeMediaContent);
     })));
     // ─── search_notes ─────────────────────────────────────────────────────────
     server.registerTool("search_notes", {
@@ -548,17 +564,18 @@ async function main() {
         description: "Read the full decrypted content of multiple notes at once. Returns all notes with their titles, content, tags, and vault names. Reports any IDs that were not found.",
         inputSchema: {
             noteIds: s(z.array(z.string().uuid()).min(1).max(20).describe("Array of note IDs to read (max 20)")),
+            includeMediaContent: s(z.boolean().optional().describe("When true, includes base64 image content for images under 500KB. Gateway mode only. Default: false.")),
         },
     }, auto.wrap(wrapToolHandler(async (args) => {
-        const { noteIds } = args;
-        return gw ? await gw.readNotes(noteIds) : await readNotes(ctx, noteIds);
+        const { noteIds, includeMediaContent } = args;
+        return gw ? await gw.readNotes(noteIds, includeMediaContent) : await readNotes(ctx, noteIds, includeMediaContent);
     })));
     // ─── 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.",
+        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), decision (significant choices made — include inputs, reasoning, alternatives considered, outcome; importance 4-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.",
         inputSchema: {
             content: s(z.string().min(1).max(1_000_000).describe("Memory content in plain text")),
-            memoryType: s(memoryTypeEnum.optional().describe("Type: fact, skill, preference, constraint, task, episodic, correction")),
+            memoryType: s(memoryTypeEnum.optional().describe("Type: fact, skill, preference, constraint, task, episodic, correction, decision")),
             summary: s(z.string().max(500).optional().describe("Optional short summary")),
             vaultId: s(z.string().uuid().optional().describe("Vault/project scope. Required unless defaultVaultId is configured for this MCP session.")),
             importance: s(z.number().int().min(1).max(5).optional().describe("Importance from 1 to 5")),
@@ -646,10 +663,11 @@ async function main() {
         description: "Read and decrypt full memory entries by IDs.",
         inputSchema: {
             memoryIds: s(z.array(z.string().uuid()).min(1).max(50).describe("Array of memory IDs to read")),
+            includeMediaContent: s(z.boolean().optional().describe("When true, includes base64 image content for images under 500KB. Gateway mode only. Default: false.")),
         },
     }, auto.wrap(wrapToolHandler(async (args) => {
-        const { memoryIds } = args;
-        return gw ? await gw.readMemories(memoryIds) : await readMemories(ctx, memoryIds);
+        const { memoryIds, includeMediaContent } = args;
+        return gw ? await gw.readMemories(memoryIds, includeMediaContent) : await readMemories(ctx, memoryIds, includeMediaContent);
     })));
     // ─── archive_memory ─────────────────────────────────────────────────────────
     server.registerTool("archive_memory", {
@@ -1260,6 +1278,23 @@ async function main() {
         const result = await gw.downloadMedia({ attachmentId });
         return JSON.stringify(result);
     })));
+    // ─── view_media ─────────────────────────────────────────────────────────
+    server.registerTool("view_media", {
+        description: "View a media attachment intelligently. Returns extracted text for all modalities, " +
+            "plus base64 image content for images under 500KB. For non-image files (PDFs, audio, " +
+            "video), returns the extracted text/transcription instead of raw bytes. " +
+            "Use download_media if you need the actual file bytes regardless of size.",
+        inputSchema: {
+            attachmentId: s(z.string().uuid().describe("Media attachment ID to view")),
+        },
+    }, auto.wrap(wrapToolHandler(async (args) => {
+        const { attachmentId } = args;
+        if (gw) {
+            const result = await gw.viewMedia({ attachmentId });
+            return JSON.stringify(result);
+        }
+        return viewMedia(ctx, attachmentId);
+    })));
     // ─── delete_media ───────────────────────────────────────────────────────
     server.registerTool("delete_media", {
         description: "Delete a media attachment and its embedding. Permanently removes the file from storage.",

package/dist/scripts/backfill-memory-embeddings.js

@@ -67,7 +67,7 @@ async function main() {
     }
     const embeddingConfig = {
         apiKey,
-        model: process.env.EMBEDDING_MODEL ?? DEFAULT_EMBEDDING_MODEL,
+        model: DEFAULT_EMBEDDING_MODEL, // Hardcoded — EMBEDDING_MODEL is for OpenAI text
     };
     const candidates = await loadBackfillCandidates(ctx, limit);
     if (candidates.length === 0) {

package/dist/session-buffer.js

@@ -159,11 +159,6 @@ export function buildTurnContent(data) {
  * using tool call metadata (inputs + outputs).
  */
 export function buildRuleBasedEpisodic(data) {
-    const durationMs = Date.now() - new Date(data.startedAt).getTime();
-    const durationMin = Math.round(durationMs / 60_000);
-    const lines = [
-        `Session: ${durationMin}min, agent=${data.agentId}.`,
-    ];
     // Extract search topics
     const searchTopics = [...new Set(data.activities
             .filter((a) => a.category === "search" && a.inputSummary)
@@ -173,6 +168,9 @@ export function buildRuleBasedEpisodic(data) {
     const readTopics = extractReadTopics(data.activities);
     // Extract write actions with context
     const writeActions = extractWriteActions(data.activities);
+    // Derive a session title from topics/actions
+    const title = deriveSessionTitle(searchTopics, readTopics, writeActions);
+    const lines = [title];
     if (searchTopics.length > 0 || readTopics.length > 0) {
         const explored = [];
         if (searchTopics.length > 0)
@@ -186,6 +184,28 @@ export function buildRuleBasedEpisodic(data) {
     }
     return lines.join("\n");
 }
+/**
+ * Derive a short session title from extracted topics and actions.
+ * Returns a concise phrase (no trailing period) summarizing the session focus.
+ */
+function deriveSessionTitle(searchTopics, readTopics, writeActions) {
+    const allTopics = [...searchTopics, ...readTopics];
+    if (allTopics.length > 0) {
+        const topicStr = allTopics.slice(0, 2).join(" and ");
+        return capitalizeAndClean(topicStr);
+    }
+    if (writeActions.length > 0) {
+        return capitalizeAndClean(writeActions[0]);
+    }
+    return "Session activity";
+}
+/** Capitalize first letter and strip trailing sentence punctuation. */
+function capitalizeAndClean(phrase) {
+    const cleaned = phrase.trim().replace(/[.!?]+$/, "");
+    if (!cleaned)
+        return "Session activity";
+    return cleaned.charAt(0).toUpperCase() + cleaned.slice(1);
+}
 /**
  * Extract what was read/explored during the session.
  * Provides context about what the agent was looking at — note titles,
@@ -453,12 +473,10 @@ export function buildTranscriptEpisodic(data) {
     if (data.transcript.length < MIN_TRANSCRIPT_ENTRIES_FOR_EPISODIC) {
         return null;
     }
-    const durationMs = Date.now() - new Date(data.startedAt).getTime();
-    const durationMin = Math.round(durationMs / 60_000);
-    const lines = [
-        `Session: ${durationMin}min, agent=${data.agentId}.`,
-        "",
-    ];
+    // Derive title from transcript entries — use first entry as session focus
+    const firstContext = data.transcript[0]?.context ?? "Session activity";
+    const title = firstContext.charAt(0).toUpperCase() + firstContext.slice(1);
+    const lines = [title, ""];
     for (const entry of data.transcript) {
         lines.push(`- ${entry.context}`);
     }

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

@@ -1,2 +1,2 @@
 import type { McpContext } from "../auth.js";
-export declare function readMemories(ctx: McpContext, memoryIds: string[]): Promise<string>;
+export declare function readMemories(ctx: McpContext, memoryIds: string[], _includeMediaContent?: boolean): Promise<string>;

package/dist/tools/read-memories.js

@@ -2,7 +2,7 @@ import { getMemoriesByIds, touchMemories, getAttachmentsForMemories, formatAttac
 import { decrypt } from "../crypto.js";
 import { logMcpUsageEvent } from "../usage.js";
 import { decryptMemoryFields } from "./decrypt-helpers.js";
-export async function readMemories(ctx, memoryIds) {
+export async function readMemories(ctx, memoryIds, _includeMediaContent) {
     const memories = await getMemoriesByIds(ctx.supabase, ctx.userId, memoryIds);
     const foundIds = new Set(memories.map((m) => m.id));
     const notFound = memoryIds.filter((id) => !foundIds.has(id));

package/dist/tools/read-note.d.ts

@@ -1,2 +1,2 @@
 import type { McpContext } from "../auth.js";
-export declare function readNote(ctx: McpContext, noteId: string): Promise<string>;
+export declare function readNote(ctx: McpContext, noteId: string, _includeMediaContent?: boolean): Promise<string>;

package/dist/tools/read-note.js

@@ -2,7 +2,7 @@ import { getNote, getVault, getAttachmentsForNotes, formatAttachmentWithExtracti
 import { decrypt } from "../crypto.js";
 import { logMcpUsageEvent } from "../usage.js";
 import { decryptNoteFields } from "./decrypt-helpers.js";
-export async function readNote(ctx, noteId) {
+export async function readNote(ctx, noteId, _includeMediaContent) {
     const note = await getNote(ctx.supabase, ctx.userId, noteId);
     if (!note) {
         return JSON.stringify({ error: "Note not found" });

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

@@ -3,4 +3,4 @@ import type { McpContext } from "../auth.js";
  * Batch-reads multiple notes by ID. Returns full decrypted content for each,
  * plus a list of any IDs that were not found.
  */
-export declare function readNotes(ctx: McpContext, noteIds: string[]): Promise<string>;
+export declare function readNotes(ctx: McpContext, noteIds: string[], _includeMediaContent?: boolean): Promise<string>;

package/dist/tools/read-notes.js

@@ -5,7 +5,7 @@ import { decryptNoteFields } from "./decrypt-helpers.js";
  * Batch-reads multiple notes by ID. Returns full decrypted content for each,
  * plus a list of any IDs that were not found.
  */
-export async function readNotes(ctx, noteIds) {
+export async function readNotes(ctx, noteIds, _includeMediaContent) {
     const notes = await getNotesByIds(ctx.supabase, ctx.userId, noteIds);
     // Build a set of found IDs to report missing ones
     const foundIds = new Set(notes.map((n) => n.id));

package/dist/tools/update-memory.d.ts

@@ -14,6 +14,7 @@ export declare function updateMemoryTool(ctx: McpContext, input: {
     relatedMemoryIds?: MemoryRelation[];
     sourceNoteIds?: string[];
     isArchived?: boolean;
+    supersededById?: string;
     metadata?: Record<string, unknown>;
 }): Promise<string>;
 export {};

package/dist/tools/update-memory.js

@@ -72,6 +72,8 @@ export async function updateMemoryTool(ctx, input) {
         updates.source_note_ids = input.sourceNoteIds;
     if (input.isArchived !== undefined)
         updates.is_archived = input.isArchived;
+    if (input.supersededById !== undefined)
+        updates.superseded_by_id = input.supersededById;
     // Merge metadata (task-specific fields like taskStatus, assignedAgentId)
     if (input.metadata !== undefined) {
         const existingMeta = (existing.metadata ?? {});

package/dist/tools/view-media.d.ts

@@ -0,0 +1,6 @@
+import type { McpContext } from "../auth.js";
+/**
+ * View a media attachment intelligently.
+ * Direct mode: returns extracted text only (no storage access).
+ */
+export declare function viewMedia(ctx: McpContext, attachmentId: string): Promise<string>;

package/dist/tools/view-media.js

@@ -0,0 +1,53 @@
+/**
+ * View a media attachment intelligently.
+ * Direct mode: returns extracted text only (no storage access).
+ */
+export async function viewMedia(ctx, attachmentId) {
+    const { data, error } = await ctx.supabase
+        .from("media_attachments")
+        .select("id, memory_id, note_id, vault_id, modality, mime_type, file_name, file_size_bytes, embedding_status, extraction_status, extracted_text, extracted_text_iv")
+        .eq("id", attachmentId)
+        .eq("user_id", ctx.userId)
+        .maybeSingle();
+    if (error)
+        return JSON.stringify({ error: "Failed to fetch attachment" });
+    if (!data)
+        return JSON.stringify({ error: "Attachment not found" });
+    let extractedText = null;
+    if (data.extracted_text && data.extracted_text_iv && ctx.masterKey) {
+        const { decrypt } = await import("../crypto.js");
+        try {
+            extractedText = await decrypt(data.extracted_text, data.extracted_text_iv, ctx.masterKey);
+        }
+        catch {
+            extractedText = null;
+        }
+    }
+    let contentNote = null;
+    if (data.modality === "image") {
+        contentNote = "base64 unavailable in direct mode — use gateway mode or download_media";
+    }
+    else {
+        const label = data.modality.charAt(0).toUpperCase() + data.modality.slice(1);
+        const verb = (data.modality === "audio" || data.modality === "video") ? "transcription" : "extracted text";
+        contentNote = `${label} — returning ${verb}. Use download_media for raw bytes.`;
+    }
+    if (!extractedText && data.extraction_status !== "completed") {
+        const note = `Extraction ${data.extraction_status} — no text content available yet.`;
+        contentNote = contentNote ? `${contentNote} ${note}` : note;
+    }
+    return JSON.stringify({
+        attachmentId: data.id,
+        memoryId: data.memory_id,
+        noteId: data.note_id,
+        modality: data.modality,
+        mimeType: data.mime_type,
+        fileName: data.file_name,
+        fileSizeBytes: data.file_size_bytes,
+        embeddingStatus: data.embedding_status,
+        extractionStatus: data.extraction_status,
+        extractedText,
+        base64Content: null,
+        contentNote,
+    });
+}

package/package.json

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