exovault-mcp-server 1.0.0

package/dist/index.js

@@ -0,0 +1,1242 @@
+#!/usr/bin/env node
+import { randomUUID } from "node:crypto";
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { z } from "zod";
+import { initialize, readConfig } from "./auth.js";
+import { listVaults } from "./tools/list-vaults.js";
+import { createVault } from "./tools/create-vault.js";
+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";
+import { writeMemory } from "./tools/write-memory.js";
+import { searchMemories } from "./tools/search-memories.js";
+import { readMemories } from "./tools/read-memories.js";
+import { archiveMemory } from "./tools/archive-memory.js";
+import { getRelatedMemories } from "./tools/get-related-memories.js";
+import { contextCheckpoint } from "./tools/context-checkpoint.js";
+import { listActiveAgents } from "./tools/list-active-agents.js";
+import { sessionStart } from "./tools/session-start.js";
+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 { 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";
+import { GatewayClient } from "./gateway-client.js";
+import { resolveGatewayConfig } from "./gateway-init.js";
+import { normalizeAgentId } from "./normalize-agent-id.js";
+import { inferTaskStatus } from "./infer-task-status.js";
+import { createAutoSession } from "./auto-session.js";
+import { wrapToolHandler } from "./tools/wrap-tool-handler.js";
+import { createSessionLifecycle } from "./session-lifecycle.js";
+import { extractToolContext } from "./session-buffer.js";
+import { createExtractionClient } from "./extraction-llm.js";
+import { readBudget, writeBudget } from "./extraction-budget.js";
+import { DEFAULT_TASK_LIFECYCLE_SETTINGS } from "./task-lifecycle-types.js";
+import { buildPlanTasksPrompt, parsePlanTasksResult } from "./task-lifecycle.js";
+import { scanOrphanedBuffers, deleteBuffer as deleteBufferFile } from "./buffer-persistence.js";
+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 memoryTypeEnum = z.enum(MEMORY_TYPES);
+/** Remind agents to checkpoint every N tool calls. */
+const CHECKPOINT_REMINDER_INTERVAL = 20;
+async function main() {
+    // ─── Detect mode: gateway (agent key) or direct (Supabase) ─────────────
+    const config = await readConfig();
+    const gwConfig = resolveGatewayConfig(config);
+    let ctx = null;
+    let gw = null;
+    let defaultVaultId = config.defaultVaultId;
+    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();
+    if (gwConfig) {
+        gw = new GatewayClient(gwConfig.apiUrl, gwConfig.agentKey, sessionRunId);
+        try {
+            const info = await gw.info();
+            gwAgentType = info.agentType;
+            gwAgentLabel = info.label;
+            process.stderr.write(`[exovault-mcp] Gateway mode: connected as "${gwAgentLabel}" (${gwAgentType}) to ${gwConfig.apiUrl}\n`);
+            // Set allowed vaults and determine default
+            allowedVaultIds = info.allowedVaultIds ?? undefined;
+            if (!defaultVaultId) {
+                if (info.restrictToVault && allowedVaultIds?.length === 1) {
+                    defaultVaultId = allowedVaultIds[0];
+                }
+                else if (info.restrictToVault && info.vaultId) {
+                    defaultVaultId = info.vaultId;
+                }
+            }
+            if (allowedVaultIds && allowedVaultIds.length > 1) {
+                process.stderr.write(`[exovault-mcp] Multi-vault access: ${allowedVaultIds.length} vaults. Specify vaultId per tool call.\n`);
+            }
+            // Auto-register session on connection — creates an active session
+            // immediately so the dashboard shows the agent even before any tools are called.
+            void gw.trackSession({
+                toolName: "_connection_start",
+                agentRunId: sessionRunId,
+                agentId: gwAgentLabel ?? "mcp_stdio",
+                agentType: gwAgentType,
+                agentLabel: gwAgentLabel,
+                vaultId: defaultVaultId,
+            });
+        }
+        catch (e) {
+            // Agent key is configured — gateway failure is fatal.
+            // Falling back to direct mode would bypass vault scope restrictions
+            // enforced by the gateway, which is a security risk.
+            throw new Error(`Gateway connection failed: ${e.message}. ` +
+                `Cannot fall back to direct mode when agent key is configured (vault scope restrictions would be bypassed). ` +
+                `Check your EXOVAULT_API_URL and EXOVAULT_AGENT_KEY settings.`);
+        }
+    }
+    if (!gw) {
+        ctx = await initialize();
+        defaultVaultId = ctx.defaultVaultId;
+        process.stderr.write("[exovault-mcp] Direct mode: connected to Supabase\n");
+    }
+    process.stderr.write(`[exovault-mcp] Session ID: ${sessionRunId}\n`);
+    // Gateway-mode vault resolver: uses defaultVaultId from config
+    function resolveVault(requestedVaultId) {
+        return requestedVaultId ?? defaultVaultId;
+    }
+    // ─── Auto-session inject ──────────────────────────────────────────────────
+    // Ensures agents get session context on their first tool call, even if they
+    // don't explicitly call session_start. This is the market-standard pattern:
+    // pre-inject context rather than relying on the LLM to remember to fetch it.
+    const auto = createAutoSession(async () => {
+        const result = gw
+            ? await gw.sessionStart({ vaultId: resolveVault() })
+            : await sessionStart(ctx, { vaultId: resolveVaultId(ctx) });
+        return result;
+    }, (msg) => process.stderr.write(`${msg}\n`));
+    // ─── LLM extraction client (optional — only when LLM config is present) ──
+    const extractionClient = config.llmApiKey && config.llmBaseUrl && config.llmModelId
+        ? createExtractionClient({
+            apiKey: config.llmApiKey,
+            baseUrl: config.llmBaseUrl,
+            modelId: config.llmModelId,
+        })
+        : undefined;
+    if (extractionClient) {
+        process.stderr.write("[exovault-mcp] LLM extraction enabled for session auto-flush\n");
+    }
+    // ─── Session lifecycle (auto-flush on idle / disconnect / signal) ─────────
+    const lifecycleAgentId = gwAgentLabel ?? normalizeAgentId(gwAgentType) ?? "mcp_stdio";
+    const lifecycle = createSessionLifecycle({
+        agentRunId: sessionRunId,
+        agentId: lifecycleAgentId,
+        vaultId: defaultVaultId ?? "",
+        idleTimeoutMs: 5 * 60 * 1000, // 5 minutes
+        minToolCalls: 5,
+        skipIfMemoriesWritten: 3,
+        // In gateway mode, the Inngest cron (session-auto-checkpoint) owns episodic
+        // writing — it has access to conversation turns for LLM summarization.
+        // The MCP server only sees tool call metadata, not actual conversation context,
+        // so its episodic summaries are thin and duplicative. Skip here, let the cron handle it.
+        checkpointFn: gw
+            ? async () => "skipped — gateway cron handles episodic"
+            : async (params) => {
+                return await contextCheckpoint(ctx, {
+                    ...params,
+                    vaultId: resolveVaultId(ctx, params.vaultId),
+                });
+            },
+        log: (msg) => process.stderr.write(`${msg}\n`),
+        onIdle: () => {
+            lifecycle.flush("idle").then(() => {
+                process.stderr.write("[exovault-mcp] Idle flush complete — process remains alive\n");
+            }).catch((e) => {
+                process.stderr.write(`[exovault-mcp] Idle flush failed: ${e.message}\n`);
+            });
+        },
+        // In gateway mode, skip LLM extraction — the Inngest cron handles episodic
+        // writing and task completion server-side. No point burning DeepSeek tokens
+        // here when checkpointFn is a no-op.
+        extractionClient: gw ? undefined : extractionClient,
+        readBudget: gw ? undefined : readBudget,
+        writeBudget: gw ? undefined : writeBudget,
+        // Task lifecycle: fetch open tasks + auto-complete at flush time
+        taskLifecycleSettings: DEFAULT_TASK_LIFECYCLE_SETTINGS,
+        fetchOpenTasks: async () => {
+            try {
+                if (gw) {
+                    const raw = await gw.listTasks({
+                        vaultId: resolveVault(),
+                        status: "in_progress",
+                    });
+                    const parsed = JSON.parse(raw);
+                    return (parsed.tasks ?? []).map((t) => ({
+                        id: t.id,
+                        title: t.title,
+                        doneWhen: t.doneWhen,
+                        status: t.status,
+                    }));
+                }
+                // Direct mode: tasks require decryption which we can't do here
+                return [];
+            }
+            catch {
+                return [];
+            }
+        },
+        updateTaskFn: async (taskId, updates) => {
+            const metaUpdate = {
+                taskStatus: updates.status,
+                completionSource: updates.completionSource,
+                completionEvidence: updates.completionEvidence,
+            };
+            if (gw) {
+                await gw.updateTask({ taskId, status: updates.status });
+                return;
+            }
+            await updateMemoryTool(ctx, { memoryId: taskId, metadata: metaUpdate });
+        },
+        createCompletedTaskFn: async (task) => {
+            if (gw) {
+                try {
+                    const result = await gw.createTask({
+                        title: task.title,
+                        description: task.evidence,
+                        status: "done",
+                        priority: 3,
+                        vaultId: resolveVault(),
+                        doneWhen: task.doneWhen,
+                        agentId: "task-lifecycle",
+                        agentRunId: sessionRunId,
+                    });
+                    const parsed = JSON.parse(result);
+                    return parsed.taskId ?? null;
+                }
+                catch {
+                    return null;
+                }
+            }
+            return null;
+        },
+        writeTaskSuggestionFn: async (content) => {
+            if (gw) {
+                await gw.writeMemory({
+                    content,
+                    memoryType: "fact",
+                    importance: 2,
+                    vaultId: resolveVault(),
+                    agentId: "task-lifecycle",
+                    agentRunId: sessionRunId,
+                });
+            }
+        },
+        // Auto-ingest session activity as a conversation turn for extraction pipeline.
+        // Use signalThreshold: 0 so ALL auto-ingested turns get flagged for extraction.
+        // Session lifecycle already filters to meaningful activity (min tool calls, non-passive),
+        // so signal detection is redundant here — let the LLM decide what's worth extracting.
+        ingestTurnFn: gw
+            ? async (content) => {
+                await gw.ingestTurn({
+                    content,
+                    role: "assistant",
+                    vaultId: defaultVaultId,
+                    agentId: lifecycleAgentId,
+                    agentRunId: sessionRunId,
+                    signalThreshold: 0,
+                });
+            }
+            : undefined,
+        ingestIntervalMs: 5 * 60 * 1000, // 5 minutes — aligned with extraction cron interval
+    });
+    /**
+     * Lifecycle tracking wrapper — records each tool call in the session buffer.
+     * Chains as the outermost layer: ltrack("name", auto.wrap(wrapToolHandler(fn)))
+     */
+    function ltrack(toolName, handler) {
+        return async (args) => {
+            const inputStr = typeof args === "object" && args !== null
+                ? JSON.stringify(args).slice(0, 200)
+                : undefined;
+            const result = await handler(args);
+            lifecycle.onToolCall(toolName, inputStr, result.content?.[0]?.text?.slice(0, 200));
+            // Record rich transcript entry for auto-episodic generation
+            if (!result.isError && typeof args === "object" && args !== null) {
+                const ctx = extractToolContext(toolName, args, result.content?.[0]?.text);
+                if (ctx)
+                    lifecycle.onTranscript(toolName, ctx);
+            }
+            // Auto-detect memory writes from write_memory / create_task results
+            if (!result.isError && (toolName === "write_memory" || toolName === "create_task")) {
+                try {
+                    const parsed = JSON.parse(result.content[0].text);
+                    if (parsed.memoryId)
+                        lifecycle.onMemoryWritten(parsed.memoryId);
+                }
+                catch { /* ignore parse errors */ }
+            }
+            // Gateway session tracking — fire-and-forget for dashboard visibility
+            if (gw) {
+                const outputStr = result.content?.[0]?.text?.slice(0, 200);
+                void gw.trackSession({
+                    toolName,
+                    agentRunId: sessionRunId,
+                    agentId: gwAgentLabel ?? "mcp_stdio",
+                    agentType: gwAgentType,
+                    agentLabel: gwAgentLabel,
+                    vaultId: defaultVaultId,
+                    inputSummary: inputStr,
+                    outputSummary: outputStr,
+                });
+            }
+            // Periodic checkpoint reminder — nudge agent every CHECKPOINT_REMINDER_INTERVAL calls
+            const count = lifecycle.getToolCallCount();
+            if (count > 0 &&
+                count % CHECKPOINT_REMINDER_INTERVAL === 0 &&
+                !lifecycle.wasCheckpointed() &&
+                toolName !== "context_checkpoint" &&
+                toolName !== "session_start") {
+                const reminder = `\n\n---\nNote: You have made ${count} tool calls this session. Call \`context_checkpoint({ sessionSummary: "..." })\` to save your progress.`;
+                if (result.content?.[0]?.text) {
+                    result.content[0].text += reminder;
+                }
+            }
+            return result;
+        };
+    }
+    // Build dynamic instructions — target ≤3,500 chars (v5).
+    // Full reference in instructions.md, returned once per session via session_start.
+    const instructionLines = [
+        "ExoVault — encrypted notes and durable agent memory.",
+        "",
+        "## Session Lifecycle (MANDATORY)",
+        "1. ON START: Call `session_start` immediately. If `isFirstConnection`, follow soul.md first-connection instructions.",
+        "2. DURING SESSION — MANDATORY, do these without being asked:",
+        "   a. **SEARCH before acting**: `search_memories` before answering questions or making decisions. `explore_graph` for deep context.",
+        "   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)",
+        "      - 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)",
+        "      - Follow-up work surfaces → `create_task` with doneWhen",
+        "   c. **Tasks**: `update_task(status='done')` IMMEDIATELY when complete. `create_task` for follow-ups.",
+        "   d. **PERIODIC CHECKPOINT**: Call `context_checkpoint` with a `sessionSummary` every ~20 tool calls or after completing a significant milestone. This saves your progress incrementally — do not wait until the end.",
+        "3. ON END: Update all tasks → call `context_checkpoint` with a final `sessionSummary` describing what happened, decisions made, and open threads. Do NOT write a separate episodic memory — the checkpoint creates it from your summary.",
+        "",
+    ];
+    if (defaultVaultId) {
+        instructionLines.push(`Default vault: ${defaultVaultId} (auto-applied to all tools).`);
+    }
+    if (allowedVaultIds && allowedVaultIds.length > 1) {
+        instructionLines.push(`Allowed vaults: ${allowedVaultIds.join(", ")}. Specify vaultId in tool calls to target a specific vault.`);
+    }
+    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).");
+    const instructionsText = instructionLines.join("\n");
+    // ── Guard: keep instructions ≤4,000 chars ─────────────────────────
+    const INSTRUCTION_CHAR_LIMIT = 4_000;
+    if (instructionsText.length > INSTRUCTION_CHAR_LIMIT) {
+        console.error(`[exovault] WARNING: Server instructions are ${instructionsText.length} chars ` +
+            `(limit ${INSTRUCTION_CHAR_LIMIT}). Slim them down to avoid token bloat.`);
+    }
+    const server = new McpServer({
+        name: "exovault",
+        version: "1.0.0",
+    }, {
+        instructions: instructionsText,
+    });
+    // Intercept registerTool to auto-track all tool calls via session lifecycle.
+    // This avoids wrapping each of the 30+ tool registrations individually.
+    const _origRegisterTool = server.registerTool.bind(server);
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    server.registerTool = (name, opts, handler) => {
+        return _origRegisterTool(name, opts, ltrack(name, handler));
+    };
+    // ─── list_vaults ──────────────────────────────────────────────────────────
+    server.registerTool("list_vaults", {
+        description: "List all vaults with their names, icons, colors, and note counts",
+    }, auto.wrap(wrapToolHandler(async () => {
+        return gw ? await gw.listVaults() : await listVaults(ctx);
+    })));
+    // ─── create_vault ──────────────────────────────────────────────────────────
+    server.registerTool("create_vault", {
+        description: "Create a new encrypted vault (idempotent by vault name).",
+        inputSchema: {
+            name: s(z.string().min(1).describe("Vault name")),
+            icon: s(z.string().optional().describe("Optional icon identifier")),
+            color: s(z.string().optional().describe("Optional color hex")),
+        },
+    }, auto.wrap(wrapToolHandler(async (args) => {
+        const { name, icon, color } = args;
+        return gw
+            ? await gw.createVault({ name, icon, color })
+            : await createVault(ctx, name, { icon, color });
+    })));
+    // ─── list_notes ───────────────────────────────────────────────────────────
+    server.registerTool("list_notes", {
+        description: "List notes with titles, tags, and content previews. Optionally filter by vault or folder.",
+        inputSchema: {
+            vaultId: s(z.string().uuid().optional().describe("Filter by vault ID")),
+            folderId: s(z.string().uuid().optional().describe("Filter by folder ID")),
+            limit: s(z.number().int().min(1).max(100).optional().describe("Max notes to return (default 20)")),
+        },
+    }, auto.wrap(wrapToolHandler(async (args) => {
+        const { vaultId, folderId, limit } = args;
+        return gw
+            ? await gw.listNotes({ vaultId: resolveVault(vaultId), folderId, limit })
+            : await listNotes(ctx, resolveVaultId(ctx, vaultId), limit);
+    })));
+    // ─── read_note ────────────────────────────────────────────────────────────
+    server.registerTool("read_note", {
+        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")),
+        },
+    }, auto.wrap(wrapToolHandler(async (args) => {
+        const { noteId } = args;
+        return gw ? await gw.readNote(noteId) : await readNote(ctx, noteId);
+    })));
+    // ─── search_notes ─────────────────────────────────────────────────────────
+    server.registerTool("search_notes", {
+        description: "Search notes by keyword. Weighted: 3x title, 2x tags, 1x content. Returns scored results.",
+        inputSchema: {
+            query: s(z.string().min(1).describe("Search query")),
+            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)")),
+        },
+    }, auto.wrap(wrapToolHandler(async (args) => {
+        const { query, vaultId, limit } = args;
+        return gw
+            ? await gw.searchNotes({ query, vaultId: resolveVault(vaultId), limit })
+            : await searchNotes(ctx, query, resolveVaultId(ctx, vaultId), limit);
+    })));
+    // ─── create_note ──────────────────────────────────────────────────────────
+    server.registerTool("create_note", {
+        description: "Create a new encrypted note in a vault, optionally inside a folder",
+        inputSchema: {
+            vaultId: s(z.string().uuid().optional().describe("Vault ID to create the note in. Defaults to defaultVaultId if configured.")),
+            title: s(z.string().min(1).max(1000).describe("Note title")),
+            content: s(z.string().max(1_000_000).describe("Note content (plain text or HTML)")),
+            tags: s(z.array(z.string().max(100)).max(50).optional().describe("Optional tags")),
+            folderId: s(z.string().uuid().optional().describe("Optional folder ID to place the note in")),
+        },
+    }, auto.wrap(wrapToolHandler(async (args) => {
+        const { vaultId, title, content, tags, folderId } = args;
+        if (gw) {
+            return await gw.createNote({ vaultId: resolveVault(vaultId), title, content, tags, folderId });
+        }
+        const effectiveVaultId = resolveVaultId(ctx, vaultId);
+        if (!effectiveVaultId) {
+            throw new Error("vaultId is required for create_note. Pass vaultId or configure defaultVaultId.");
+        }
+        return await createNote(ctx, effectiveVaultId, title, content, tags);
+    })));
+    // ─── update_note ──────────────────────────────────────────────────────────
+    server.registerTool("update_note", {
+        description: "Update an existing note's title, content, or tags",
+        inputSchema: {
+            noteId: s(z.string().uuid().describe("The note ID to update")),
+            title: s(z.string().max(1000).optional().describe("New title")),
+            content: s(z.string().max(1_000_000).optional().describe("New content (plain text or HTML)")),
+            tags: s(z.array(z.string().max(100)).max(50).optional().describe("New tags (replaces existing)")),
+        },
+    }, auto.wrap(wrapToolHandler(async (args) => {
+        const { noteId, title, content, tags } = args;
+        return gw
+            ? await gw.updateNote({ noteId, title, content, tags })
+            : await updateNote(ctx, noteId, title, content, tags);
+    })));
+    // ─── delete_note ─────────────────────────────────────────────────────────
+    server.registerTool("delete_note", {
+        description: "Permanently delete a note by ID",
+        inputSchema: {
+            noteId: s(z.string().uuid().describe("The note ID to delete")),
+        },
+    }, auto.wrap(wrapToolHandler(async (args) => {
+        const { noteId } = args;
+        return gw ? await gw.deleteNote(noteId) : await deleteNote(ctx, noteId);
+    })));
+    // ─── list_folders ──────────────────────────────────────────────────────────
+    server.registerTool("list_folders", {
+        description: "List folders in a vault. Returns a flat list of folders with names, parent IDs, and sort order. Client can build the tree structure.",
+        inputSchema: {
+            vaultId: s(z.string().uuid().optional().describe("Vault ID. Defaults to defaultVaultId.")),
+        },
+    }, auto.wrap(wrapToolHandler(async (args) => {
+        const { vaultId } = args;
+        if (gw) {
+            return await gw.listFolders({ vaultId: resolveVault(vaultId) });
+        }
+        throw new Error("list_folders is only available in gateway mode.");
+    })));
+    // ─── create_folder ────────────────────────────────────────────────────────
+    server.registerTool("create_folder", {
+        description: "Create a new folder in a vault. Folders organize notes hierarchically (like Obsidian). Use parentId to create subfolders.",
+        inputSchema: {
+            vaultId: s(z.string().uuid().optional().describe("Vault ID. Defaults to defaultVaultId.")),
+            name: s(z.string().min(1).max(500).describe("Folder name")),
+            parentId: s(z.string().uuid().optional().describe("Parent folder ID for nesting. Omit for root-level folder.")),
+            icon: s(z.string().max(8).optional().describe("Emoji icon for the folder (e.g. '📁'). Omit for default icon.")),
+        },
+    }, auto.wrap(wrapToolHandler(async (args) => {
+        const { vaultId, name, parentId, icon } = args;
+        if (gw) {
+            return await gw.createFolder({ vaultId: resolveVault(vaultId), name, parentId, icon });
+        }
+        throw new Error("create_folder is only available in gateway mode.");
+    })));
+    // ─── move_note ────────────────────────────────────────────────────────────
+    server.registerTool("move_note", {
+        description: "Move a note to a different folder. Set folderId to null to move to the root (unfiled).",
+        inputSchema: {
+            noteId: s(z.string().uuid().describe("The note ID to move")),
+            folderId: s(z.string().uuid().optional().describe("Destination folder ID. Omit or null to move to root (unfiled).")),
+        },
+    }, auto.wrap(wrapToolHandler(async (args) => {
+        const { noteId, folderId } = args;
+        if (gw) {
+            return await gw.moveNote({ noteId, folderId: folderId ?? null });
+        }
+        throw new Error("move_note is only available in gateway mode.");
+    })));
+    // ─── read_notes (batch) ─────────────────────────────────────────────────
+    server.registerTool("read_notes", {
+        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)")),
+        },
+    }, auto.wrap(wrapToolHandler(async (args) => {
+        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.",
+        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")),
+            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")),
+            confidence: s(z.number().int().min(1).max(5).optional().describe("Confidence from 1 to 5")),
+            agentId: s(z.string().optional().describe("Agent identifier")),
+            agentType: s(z.string().optional().describe("Agent type")),
+            modelId: s(z.string().optional().describe("Model used to create this memory")),
+            agentRunId: s(z.string().optional().describe("Agent run identifier")),
+            sourceMessageId: s(z.string().uuid().optional().describe("Source message UUID")),
+            writeReason: s(z.string().optional().describe("Why this memory should be stored")),
+            externalWriteId: s(z.string().optional().describe("Idempotency key for upsert behavior")),
+            relatedMemoryIds: s(z.array(z.object({
+                memoryId: z.string().uuid(),
+                relationType: z.enum(["derived_from", "contradicts", "refines", "part_of", "supersedes"]),
+            })).optional().describe("Links to related memories with relation type")),
+            sourceNoteIds: s(z.array(z.string().uuid()).optional().describe("Note UUIDs this memory was extracted from")),
+            supersededById: s(z.string().uuid().optional().describe("Memory ID that supersedes this one (for corrections)")),
+            entities: s(z.array(z.string()).optional().describe("Extracted entity names (people, projects, tools, concepts) for cross-linking")),
+            dedup: s(z.boolean().optional().describe("Run semantic dedup before writing. >92% match = skip, >80% = supersede old.")),
+        },
+    }, auto.wrap(wrapToolHandler(async (args) => {
+        const input = args;
+        const normalized = {
+            ...input,
+            agentId: gwAgentLabel ?? normalizeAgentId(input.agentId) ?? input.agentId,
+            agentRunId: input.agentRunId ?? sessionRunId,
+        };
+        if (gw) {
+            return await gw.writeMemory({ ...normalized, vaultId: resolveVault(input.vaultId) });
+        }
+        return await writeMemory(ctx, normalized);
+    })));
+    // ─── search_memories ────────────────────────────────────────────────────────
+    server.registerTool("search_memories", {
+        description: "Search durable memories semantically with optional filters and recency fallback. Use 'entity' for exact entity-based search instead of semantic search.",
+        inputSchema: {
+            query: s(z.string().min(1).describe("Natural language query (ignored when entity is provided)")),
+            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.4)")),
+            vaultId: s(z.string().uuid().optional().describe("Optional vault/project filter")),
+            memoryType: s(memoryTypeEnum.optional().describe("Optional memory type filter")),
+            includeArchived: s(z.boolean().optional().describe("Include archived memories")),
+            entity: s(z.string().optional().describe("Search by entity name using JSONB containment instead of semantic search")),
+            compact: s(z.boolean().optional().describe("Return truncated content previews (200 chars) instead of full content. Use read_memories for full content on specific IDs.")),
+            decayHalfLife: s(z.number().int().min(1).max(365).optional().describe("Temporal decay half-life in days (default 30). Older memories score lower unless importance >= 4.")),
+            diversity: s(z.number().min(0).max(1).optional().describe("MMR diversity balance 0-1 (default 0.7). Higher = more relevance, lower = more diversity.")),
+        },
+    }, auto.wrap(wrapToolHandler(async (args) => {
+        const input = args;
+        if (gw) {
+            return await gw.searchMemories({ ...input, vaultId: resolveVault(input.vaultId) });
+        }
+        return await searchMemories(ctx, { ...input, vaultId: resolveVaultId(ctx, input.vaultId) });
+    })));
+    // ─── read_memories ──────────────────────────────────────────────────────────
+    server.registerTool("read_memories", {
+        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")),
+        },
+    }, auto.wrap(wrapToolHandler(async (args) => {
+        const { memoryIds } = args;
+        return gw ? await gw.readMemories(memoryIds) : await readMemories(ctx, memoryIds);
+    })));
+    // ─── archive_memory ─────────────────────────────────────────────────────────
+    server.registerTool("archive_memory", {
+        description: "Archive or unarchive a memory entry by ID.",
+        inputSchema: {
+            memoryId: s(z.string().uuid().describe("Memory ID")),
+            archived: s(z.boolean().optional().describe("True to archive, false to unarchive (default true)")),
+        },
+    }, auto.wrap(wrapToolHandler(async (args) => {
+        const { memoryId, archived } = args;
+        return gw
+            ? await gw.archiveMemory(memoryId, archived ?? true)
+            : await archiveMemory(ctx, memoryId, archived ?? true);
+    })));
+    // ─── update_memory ─────────────────────────────────────────────────────────
+    server.registerTool("update_memory", {
+        description: "Update an existing memory's content, summary, type, importance, confidence, entities, or other fields. Re-encrypts and re-indexes embeddings when content changes.",
+        inputSchema: {
+            memoryId: s(z.string().uuid().describe("The memory ID to update")),
+            content: s(z.string().min(1).max(1_000_000).optional().describe("New content (replaces existing)")),
+            summary: s(z.string().max(500).optional().describe("New summary (empty string to clear)")),
+            memoryType: s(memoryTypeEnum.optional().describe("New memory type")),
+            importance: s(z.number().int().min(1).max(5).optional().describe("New importance (1-5)")),
+            confidence: s(z.number().int().min(1).max(5).optional().describe("New confidence (1-5)")),
+            entities: s(z.array(z.string()).optional().describe("New entities (replaces existing)")),
+            relatedMemoryIds: s(z.array(z.object({
+                memoryId: z.string().uuid(),
+                relationType: z.enum(["derived_from", "contradicts", "refines", "part_of", "supersedes"]),
+            })).optional().describe("New related memories (replaces existing)")),
+            sourceNoteIds: s(z.array(z.string().uuid()).optional().describe("New source note IDs (replaces existing)")),
+            isArchived: s(z.boolean().optional().describe("Archive or unarchive")),
+            metadata: s(z.record(z.string(), z.unknown()).optional().describe("Metadata fields to merge (not replace). For tasks: { taskStatus: 'in_progress', assignedAgentId: 'claude_code' }")),
+        },
+    }, auto.wrap(wrapToolHandler(async (args) => {
+        const input = args;
+        return gw ? await gw.updateMemory(input) : await updateMemoryTool(ctx, input);
+    })));
+    // ─── get_related_memories ────────────────────────────────────────────────────
+    server.registerTool("get_related_memories", {
+        description: "Given a memory ID, returns related memories: those listed in relatedMemoryIds, memories sharing entities, and the supersession chain.",
+        inputSchema: {
+            memoryId: s(z.string().uuid().describe("The memory ID to find relations for")),
+            limit: s(z.number().int().min(1).max(50).optional().describe("Max related memories to return (default 20)")),
+            vaultId: s(z.string().uuid().optional().describe("Vault scope for related memory lookup. Uses default vault if omitted.")),
+        },
+    }, auto.wrap(wrapToolHandler(async (args) => {
+        const { memoryId, limit, vaultId } = args;
+        return gw
+            ? await gw.getRelatedMemories(memoryId, limit, resolveVault(vaultId))
+            : await getRelatedMemories(ctx, memoryId, limit);
+    })));
+    // ─── context_checkpoint ──────────────────────────────────────────────────
+    server.registerTool("context_checkpoint", {
+        description: "End-of-session checkpoint. Provide a sessionSummary describing what happened, decisions made, and open threads. Optionally include memories to bulk-save. The summary is stored as an episodic memory for future sessions.",
+        inputSchema: {
+            memories: s(z.array(z.object({
+                content: z.string().min(1).max(1_000_000),
+                memoryType: memoryTypeEnum.optional(),
+                summary: z.string().max(500).optional(),
+                importance: z.number().int().min(1).max(5).optional(),
+                confidence: z.number().int().min(1).max(5).optional(),
+                entities: z.array(z.string()).optional(),
+                writeReason: z.string().optional(),
+                relatedMemoryIds: z.array(z.object({
+                    memoryId: z.string().uuid(),
+                    relationType: z.enum(["derived_from", "contradicts", "refines", "part_of", "supersedes"]),
+                })).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.")),
+            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")),
+            modelId: s(z.string().optional().describe("Model used")),
+            agentRunId: s(z.string().optional().describe("Run ID for checkpoint idempotency")),
+            dedup: s(z.boolean().optional().describe("Run semantic dedup per memory (default true)")),
+        },
+    }, auto.wrap(wrapToolHandler(async (args) => {
+        const input = args;
+        const normalized = {
+            ...input,
+            agentId: gwAgentLabel ?? normalizeAgentId(input.agentId) ?? input.agentId,
+            agentRunId: input.agentRunId ?? sessionRunId,
+        };
+        if (gw) {
+            return await gw.contextCheckpoint({ ...normalized, vaultId: resolveVault(input.vaultId) });
+        }
+        return await contextCheckpoint(ctx, { ...normalized, vaultId: resolveVaultId(ctx, input.vaultId) });
+    })));
+    // ─── list_active_agents ─────────────────────────────────────────────────
+    server.registerTool("list_active_agents", {
+        description: "List agents that have recently written memories. Useful for cross-agent coordination and understanding who has been active.",
+        inputSchema: {
+            sinceDays: s(z.number().int().min(1).max(365).optional().describe("Look back N days (default 30)")),
+            limit: s(z.number().int().min(1).max(100).optional().describe("Max agents to return (default 20)")),
+        },
+    }, auto.wrap(wrapToolHandler(async (args) => {
+        const { sinceDays, limit } = args;
+        return gw
+            ? await gw.listActiveAgents(sinceDays, limit)
+            : await listActiveAgents(ctx, { sinceDays, limit });
+    })));
+    // ─── cleanup_memories ────────────────────────────────────────────────────
+    server.registerTool("cleanup_memories", {
+        description: "Find and archive stale, low-importance, superseded, or failed-indexing memories. Supports dry-run mode to preview candidates before archiving. Use this periodically to keep memory clean.",
+        inputSchema: {
+            vaultId: s(z.string().uuid().optional().describe("Vault to clean up. Defaults to defaultVaultId.")),
+            maxEpisodicAgeDays: s(z.number().int().min(1).max(365).optional().describe("Archive episodic memories older than N days (default 30)")),
+            maxImportance: s(z.number().int().min(1).max(5).optional().describe("Archive memories with importance <= this (default 1)")),
+            staleAfterDays: s(z.number().int().min(1).max(365).optional().describe("Archive stale memories not updated in N days (default 14)")),
+            dryRun: s(z.boolean().optional().describe("Preview candidates without archiving (default false)")),
+        },
+    }, auto.wrap(wrapToolHandler(async (args) => {
+        const input = args;
+        if (gw) {
+            return await gw.cleanupMemories({ ...input, vaultId: resolveVault(input.vaultId) });
+        }
+        return await cleanupMemories(ctx, input);
+    })));
+    // ─── session_start ──────────────────────────────────────────────────────
+    server.registerTool("session_start", {
+        description: "Load recent context at the start of a session. Returns recent session summaries (episodic), high-importance facts, active tasks, constraints, available vaults, and recently active agents. Optionally accepts a query for targeted context retrieval. Call this at the beginning of every session to resume where you left off.",
+        inputSchema: {
+            vaultId: s(z.string().uuid().optional().describe("Scope to a specific vault")),
+            query: s(z.string().optional().describe("Optional query to retrieve targeted context via semantic search")),
+            mode: s(z.enum(["default", "planning", "incident", "handoff", "deep", "minimal", "none"]).optional().describe("Context profile preset. 'planning'=more facts/tasks, 'incident'=more recent context, 'handoff'=session transfer, 'deep'=maximum context, 'minimal'=lightweight (1 episodic, 2 facts), 'none'=skip all memory queries (vaults+agents only). Explicit max* params override mode.")),
+            maxEpisodic: s(z.number().int().min(0).max(10).optional().describe("Max recent session summaries (default depends on mode)")),
+            maxFacts: s(z.number().int().min(0).max(20).optional().describe("Max important facts (default depends on mode)")),
+            maxTasks: s(z.number().int().min(0).max(10).optional().describe("Max active tasks (default depends on mode)")),
+            maxConstraints: s(z.number().int().min(0).max(20).optional().describe("Max constraints (default depends on mode)")),
+            summaryOnly: s(z.boolean().optional().describe("Return memory summaries instead of full content (default: true). Set to false to get full content.")),
+            includeDocuments: s(z.array(z.enum(["soul", "instructions", "skills", "checks"])).optional().describe("Which documents to include in the response (default: [\"soul\"]). Use read_document to fetch others on demand.")),
+        },
+    }, wrapToolHandler(async (args) => {
+        // Mark injected so auto-session doesn't fire on subsequent tool calls
+        auto.markInjected();
+        const input = args;
+        const agentId = gwAgentLabel ?? gwAgentType ?? "mcp_stdio";
+        if (gw) {
+            return await gw.sessionStart({ ...input, vaultId: resolveVault(input.vaultId) });
+        }
+        return await sessionStart(ctx, { ...input, agentId, vaultId: resolveVaultId(ctx, input.vaultId) });
+    }));
+    // ─── get_links ─────────────────────────────────────────────────────────────
+    server.registerTool("get_links", {
+        description: "Get knowledge graph links for a note or memory. Returns outgoing, incoming, or both directions. Use this to explore connections between notes and memories.",
+        inputSchema: {
+            nodeType: s(z.enum(["note", "memory"]).describe("Type of the node to get links for")),
+            nodeId: s(z.string().uuid().describe("ID of the note or memory")),
+            direction: s(z.enum(["outgoing", "incoming", "both"]).optional().describe("Link direction filter (default: both)")),
+            limit: s(z.number().int().min(1).max(200).optional().describe("Max links to return (default 50)")),
+        },
+    }, auto.wrap(wrapToolHandler(async (args) => {
+        const input = args;
+        return gw ? await gw.getLinks(input) : await getLinks(ctx, input);
+    })));
+    // ─── add_link ─────────────────────────────────────────────────────────────
+    server.registerTool("add_link", {
+        description: "Create a knowledge graph link between two nodes (notes and/or memories). Supports relation types: wiki_link, derived_from, contradicts, refines, part_of, supersedes, source_of, references, manual.",
+        inputSchema: {
+            sourceType: s(z.enum(["note", "memory"]).describe("Type of the source node")),
+            sourceId: s(z.string().uuid().describe("ID of the source node")),
+            targetType: s(z.enum(["note", "memory"]).describe("Type of the target node")),
+            targetId: s(z.string().uuid().describe("ID of the target node")),
+            relationType: s(z.enum([
+                "wiki_link", "derived_from", "contradicts", "refines",
+                "part_of", "supersedes", "source_of", "references", "manual",
+            ]).describe("Type of relationship between the nodes")),
+            label: s(z.string().max(500).optional().describe("Optional display label for the link (will be encrypted)")),
+        },
+    }, auto.wrap(wrapToolHandler(async (args) => {
+        const input = args;
+        return gw ? await gw.addLink(input) : await addLink(ctx, input);
+    })));
+    // ─── remove_link ──────────────────────────────────────────────────────────
+    server.registerTool("remove_link", {
+        description: "Remove a knowledge graph link by its ID.",
+        inputSchema: {
+            linkId: s(z.string().uuid().describe("The link ID to remove")),
+        },
+    }, auto.wrap(wrapToolHandler(async (args) => {
+        const { linkId } = args;
+        return gw ? await gw.removeLink(linkId) : await removeLink(ctx, linkId);
+    })));
+    // ─── explore_graph ──────────────────────────────────────────────────────
+    server.registerTool("explore_graph", {
+        description: "Navigate the knowledge graph WITHOUT burning LLM tokens. " +
+            "Provide a `query` (semantic search for entry points) and/or `nodeId`+`nodeType` (start from a specific node). " +
+            "Returns a map of nodes (memories + notes with summaries) and edges (relationships). " +
+            "Use this to discover connections, then call `read_memories` or `read_note` to dive deeper into specific nodes. " +
+            "Replaces rlm_query — zero LLM calls, pure DB traversal.",
+        inputSchema: {
+            query: s(z.string().max(2000).optional().describe("Semantic search query to find entry point nodes")),
+            nodeId: s(z.string().uuid().optional().describe("Start traversal from this specific node")),
+            nodeType: s(z.enum(["note", "memory"]).optional().describe("Type of nodeId (required when nodeId is provided)")),
+            maxHops: s(z.number().int().min(1).max(5).optional().describe("Max traversal depth (default 2, max 5)")),
+            maxNodes: s(z.number().int().min(1).max(200).optional().describe("Max nodes to return (default 50, max 200)")),
+            vaultId: s(z.string().uuid().optional().describe("Vault to scope search to")),
+        },
+    }, auto.wrap(wrapToolHandler(async (args) => {
+        const input = args;
+        return gw
+            ? await gw.exploreGraph(input)
+            : await exploreGraph(ctx, input);
+    })));
+    // ─── create_task ─────────────────────────────────────────────────────────
+    // Thin wrapper around writeMemory — tasks are stored as memories with memoryType='task'
+    const taskStatusEnum = z.enum(["backlog", "todo", "in_progress", "done", "blocked"]);
+    server.registerTool("create_task", {
+        description: "Create a new task on the kanban board. Tasks are stored as memories with memoryType='task'. Returns the created task/memory ID.",
+        inputSchema: {
+            title: s(z.string().min(1).max(500).describe("Task title (plaintext — encrypted before storage)")),
+            description: s(z.string().max(5000).optional().describe("Optional task description (plaintext — encrypted before storage)")),
+            vaultId: s(z.string().uuid().optional().describe("Vault to scope the task to. Defaults to defaultVaultId.")),
+            status: s(taskStatusEnum.optional().describe("Initial status. Defaults to 'todo'.")),
+            priority: s(z.number().int().min(1).max(5).optional().describe("Priority 1-5 (5=critical). Defaults to 3.")),
+            agentId: s(z.string().max(200).optional().describe("Agent that created this task.")),
+            agentRunId: s(z.string().max(200).optional().describe("Agent run/session ID.")),
+            assignedAgentId: s(z.string().max(200).optional().describe("Agent assigned to work on this task. Use 'any' to let any agent pick it up.")),
+            doneWhen: s(z.string().max(1000).optional().describe("Natural language completion criteria. When set, ExoVault can auto-detect task completion.")),
+        },
+    }, auto.wrap(wrapToolHandler(async (args) => {
+        const { title, description, status, priority, assignedAgentId, doneWhen, ...rest } = args;
+        // Infer status from title/description if caller left it as default "todo"
+        const effectiveStatus = inferTaskStatus(title, description, status) ?? status ?? "todo";
+        const metadata = { taskStatus: effectiveStatus };
+        if (assignedAgentId)
+            metadata.assignedAgentId = assignedAgentId;
+        if (doneWhen)
+            metadata.doneWhen = doneWhen;
+        const memoryInput = {
+            content: title,
+            summary: description,
+            memoryType: "task",
+            importance: priority ?? 3,
+            metadata,
+            agentId: rest.agentId,
+            agentRunId: rest.agentRunId ?? sessionRunId,
+            vaultId: rest.vaultId,
+        };
+        if (gw) {
+            return await gw.createTask({
+                title,
+                description,
+                status: effectiveStatus,
+                priority: priority ?? 3,
+                agentId: rest.agentId,
+                agentRunId: rest.agentRunId ?? sessionRunId,
+                assignedAgentId,
+                doneWhen,
+                vaultId: resolveVault(rest.vaultId),
+            });
+        }
+        return await writeMemory(ctx, memoryInput);
+    })));
+    // ─── update_task ────────────────────────────────────────────────────────
+    // Thin wrapper around updateMemoryTool — updates metadata JSONB for task fields
+    server.registerTool("update_task", {
+        description: "Update an existing task's status, priority, or assignment on the kanban board. Tasks are memories — this updates the memory's metadata and importance.",
+        inputSchema: {
+            taskId: s(z.string().uuid().describe("ID of the task (memory) to update.")),
+            status: s(taskStatusEnum.optional().describe("New status for the task.")),
+            priority: s(z.number().int().min(1).max(5).optional().describe("New priority (1-5).")),
+            assignedAgentId: s(z.string().max(200).nullable().optional().describe("Assign to a specific agent, 'any' for any agent, or null to unassign.")),
+            doneWhen: s(z.string().max(1000).nullable().optional().describe("Natural language completion criteria. Set null to clear.")),
+        },
+    }, auto.wrap(wrapToolHandler(async (args) => {
+        const { taskId, status, priority, assignedAgentId, doneWhen } = args;
+        const metaUpdate = {};
+        if (status !== undefined)
+            metaUpdate.taskStatus = status;
+        if (assignedAgentId !== undefined)
+            metaUpdate.assignedAgentId = assignedAgentId;
+        if (doneWhen !== undefined)
+            metaUpdate.doneWhen = doneWhen;
+        if (gw) {
+            return await gw.updateTask({ taskId, status, priority, assignedAgentId, doneWhen });
+        }
+        const memoryInput = { memoryId: taskId };
+        if (priority !== undefined)
+            memoryInput.importance = priority;
+        if (Object.keys(metaUpdate).length > 0)
+            memoryInput.metadata = metaUpdate;
+        return await updateMemoryTool(ctx, memoryInput);
+    })));
+    // ─── list_tasks ─────────────────────────────────────────────────────────
+    server.registerTool("list_tasks", {
+        description: "List tasks from the kanban board. Returns decrypted titles and descriptions. Filter by vault, status, assigned agent, or limit.",
+        inputSchema: {
+            vaultId: s(z.string().uuid().optional().describe("Filter tasks by vault. Defaults to defaultVaultId.")),
+            status: s(taskStatusEnum.optional().describe("Filter tasks by status.")),
+            assignedAgentId: s(z.string().max(200).optional().describe("Filter tasks assigned to a specific agent. Use your agent type to find tasks assigned to you.")),
+            limit: s(z.number().int().min(1).max(200).optional().describe("Max tasks to return (default 100).")),
+        },
+    }, auto.wrap(wrapToolHandler(async (args) => {
+        const input = args;
+        if (gw) {
+            return await gw.listTasks({
+                ...input,
+                vaultId: resolveVault(input.vaultId),
+            });
+        }
+        // Direct mode: list_tasks still needs gateway or a direct query
+        // For now, use searchMemories with memoryType='task' as a fallback
+        return await searchMemories(ctx, {
+            query: input.status ?? "task",
+            memoryType: "task",
+            vaultId: input.vaultId,
+            topK: input.limit ?? 100,
+            includeArchived: false,
+        });
+    })));
+    // ─── create_plan_tasks ────────────────────────────────────────────────────
+    // Decomposes a natural language plan into tracked tasks using LLM
+    server.registerTool("create_plan_tasks", {
+        description: "Break a plan into tracked tasks on the kanban board. Uses LLM to decompose the plan into actionable tasks with completion criteria (doneWhen). The first task is set to 'in_progress', rest to 'todo'. All share a planGroupId for grouping.",
+        inputSchema: {
+            plan: s(z.string().min(1).max(50_000).describe("Natural language plan description to decompose into tasks")),
+            vaultId: s(z.string().uuid().optional().describe("Vault to create tasks in. Defaults to defaultVaultId.")),
+            assignedAgentId: s(z.string().max(200).optional().describe("Agent to assign all plan tasks to.")),
+            agentId: s(z.string().max(200).optional().describe("Agent creating the plan.")),
+            agentRunId: s(z.string().max(200).optional().describe("Agent run/session ID.")),
+        },
+    }, auto.wrap(wrapToolHandler(async (args) => {
+        const { plan, assignedAgentId, ...rest } = args;
+        if (!extractionClient) {
+            throw new Error("create_plan_tasks requires LLM configuration (llmApiKey, llmBaseUrl, llmModelId in config). " +
+                "Create tasks manually with create_task instead.");
+        }
+        // Fetch existing tasks for dedup context
+        let existingTasks = [];
+        try {
+            if (gw) {
+                const raw = await gw.listTasks({ vaultId: resolveVault(rest.vaultId) });
+                const parsed = JSON.parse(raw);
+                existingTasks = (parsed.tasks ?? []).map((t) => ({ title: t.title, status: t.status }));
+            }
+        }
+        catch { /* ignore — dedup is optional */ }
+        // Build prompt and call LLM
+        const { prompt, systemPrompt } = buildPlanTasksPrompt(plan, existingTasks);
+        const llmResult = await extractionClient.extract(`${systemPrompt}\n\n${prompt}`, 500);
+        const planned = parsePlanTasksResult(llmResult.text);
+        if (!planned || planned.length === 0) {
+            return JSON.stringify({ planGroupId: null, tasks: [], message: "LLM returned no tasks. Create them manually." });
+        }
+        // Generate planGroupId and create tasks
+        const planGroupId = randomUUID();
+        const created = [];
+        for (let i = 0; i < planned.length; i++) {
+            const task = planned[i];
+            const status = i === 0 ? "in_progress" : "todo";
+            const metadata = {
+                taskStatus: status,
+                planGroupId,
+                doneWhen: task.doneWhen,
+            };
+            if (assignedAgentId)
+                metadata.assignedAgentId = assignedAgentId;
+            try {
+                if (gw) {
+                    const result = await gw.createTask({
+                        title: task.title,
+                        description: task.description,
+                        status,
+                        priority: task.priority,
+                        agentId: rest.agentId,
+                        agentRunId: rest.agentRunId ?? sessionRunId,
+                        assignedAgentId,
+                        doneWhen: task.doneWhen,
+                        vaultId: resolveVault(rest.vaultId),
+                        dedup: true,
+                    });
+                    const parsed = JSON.parse(result);
+                    created.push({ taskId: parsed.taskId, title: task.title, status });
+                }
+                else {
+                    const result = await writeMemory(ctx, {
+                        content: task.description
+                            ? `${task.title}\n\n${task.description}`
+                            : task.title,
+                        summary: task.title,
+                        memoryType: "task",
+                        importance: task.priority,
+                        metadata,
+                        agentId: rest.agentId,
+                        agentRunId: rest.agentRunId ?? sessionRunId,
+                        vaultId: rest.vaultId,
+                    });
+                    const parsed = JSON.parse(result);
+                    created.push({ taskId: parsed.memoryId, title: task.title, status });
+                }
+            }
+            catch (e) {
+                process.stderr.write(`[exovault-mcp] create_plan_tasks: failed to create "${task.title}": ${e.message}\n`);
+            }
+        }
+        return JSON.stringify({ planGroupId, tasks: created }, null, 2);
+    })));
+    // ─── ingest_turn ─────────────────────────────────────────────────────────
+    server.registerTool("ingest_turn", {
+        description: "Push a conversation turn for automatic fact extraction. ExoVault will run signal detection and, if the turn contains extractable knowledge, queue it for background LLM extraction. Use this to capture important conversation exchanges that should become durable memories. Only available in gateway mode.",
+        inputSchema: {
+            content: s(z.string().min(1).max(100_000).describe("The conversation turn content (plaintext)")),
+            role: s(z.enum(["user", "assistant"]).describe("Who said this — 'user' or 'assistant'")),
+            vaultId: s(z.string().uuid().optional().describe("Vault to scope the turn to. Defaults to defaultVaultId.")),
+            agentId: s(z.string().optional().describe("Agent identifier")),
+            agentRunId: s(z.string().optional().describe("Agent run/session ID")),
+        },
+    }, auto.wrap(wrapToolHandler(async (args) => {
+        const { content, role, vaultId, agentId, agentRunId } = args;
+        if (gw) {
+            return await gw.ingestTurn({
+                content,
+                role,
+                vaultId: resolveVault(vaultId),
+                agentId: gwAgentLabel ?? normalizeAgentId(agentId) ?? agentId,
+                agentRunId: agentRunId ?? sessionRunId,
+            });
+        }
+        // Direct mode: no extraction pipeline available without gateway
+        throw new Error("ingest_turn is only available in gateway mode. " +
+            "Configure EXOVAULT_AGENT_KEY to use automatic fact extraction.");
+    })));
+    // ─── update_document ────────────────────────────────────────────────────
+    server.registerTool("update_document", {
+        description: "Append content to an agent-editable vault document (instructions, skills, or checks). Documents are append-only — agents cannot replace existing content. Soul document is read-only. Use read_document to view current content before appending.",
+        inputSchema: {
+            vaultId: s(z.string().uuid().optional().describe("Vault ID. Defaults to defaultVaultId.")),
+            documentType: s(z.enum(["instructions", "skills", "checks"]).describe("Document to append to. 'instructions' = operational guidance, 'skills' = learned procedures, 'checks' = validation/QA checks.")),
+            appendContent: s(z.string().min(1).max(100_000).describe("Markdown content to append to the document.")),
+        },
+    }, auto.wrap(wrapToolHandler(async (args) => {
+        const input = args;
+        if (gw) {
+            return await gw.updateDocument({
+                vaultId: resolveVault(input.vaultId),
+                documentType: input.documentType,
+                appendContent: input.appendContent,
+            });
+        }
+        throw new Error("update_document is only available in gateway mode. Configure EXOVAULT_AGENT_KEY to use this feature.");
+    })));
+    // ─── read_document ─────────────────────────────────────────────────────
+    server.registerTool("read_document", {
+        description: "Read a vault document on demand. Documents contain operational guidance that supplements the server instructions. Types: 'soul' (agent identity, read-only), 'instructions' (operational guide — memory protocols, search triggers, task lifecycle, entity conventions), 'skills' (learned procedures), 'checks' (quality gates). soul.md is included in session_start by default; use this tool to fetch the others when needed.",
+        inputSchema: {
+            vaultId: s(z.string().uuid().optional().describe("Vault ID. Defaults to defaultVaultId.")),
+            documentType: s(z.enum(["soul", "instructions", "skills", "checks"]).describe("Document to read.")),
+        },
+    }, auto.wrap(wrapToolHandler(async (args) => {
+        const input = args;
+        if (gw) {
+            return await gw.readDocument({
+                vaultId: resolveVault(input.vaultId),
+                documentType: input.documentType,
+            });
+        }
+        throw new Error("read_document is only available in gateway mode. Configure EXOVAULT_AGENT_KEY to use this feature.");
+    })));
+    // ─── read_docs (public documentation) ─────────────────────────────────────
+    server.registerTool("read_docs", {
+        description: "Read ExoVault product documentation. Use { list: true } to get all available doc slugs. " +
+            "Use { slug: 'getting-started/quickstart' } to read a specific page as raw markdown. " +
+            "Docs include agent-reference comment blocks with compact structured data for efficient consumption.",
+        inputSchema: {
+            slug: s(z.string().optional().describe("Doc page slug, e.g. 'getting-started/quickstart' or 'mcp-tools/write-memory'")),
+            list: s(z.boolean().optional().describe("Set true to list all available doc pages")),
+        },
+    }, auto.wrap(wrapToolHandler(async (args) => {
+        const input = args;
+        if (gw) {
+            return await gw.readDocs(input);
+        }
+        // Direct mode: use hardcoded production URL (public endpoint)
+        const apiUrl = "https://exovault.co";
+        const res = await fetch(`${apiUrl}/api/agent/read-docs`, {
+            method: "POST",
+            headers: { "Content-Type": "application/json" },
+            body: JSON.stringify(input),
+        });
+        if (!res.ok) {
+            const err = await res.json().catch(() => ({ error: res.statusText }));
+            throw new Error(`read_docs failed: ${err.error}`);
+        }
+        return JSON.stringify(await res.json());
+    })));
+    // ─── send_message ─────────────────────────────────────────────────────────
+    server.registerTool("send_message", {
+        description: "Send a directed message to another agent, the user, or broadcast to all agents. " +
+            "Messages are transient coordination artifacts (not durable memories). " +
+            "Categories: directive (instruction), question (needs answer), info (FYI), task (work request), alert (urgent). " +
+            "Priority 1-5 (5=critical). Messages auto-expire after 30 days by default.",
+        inputSchema: {
+            targetId: s(z.string().min(1).max(200).describe("Recipient: specific agentId, 'user', or '*' for broadcast")),
+            category: s(z.enum(["directive", "question", "info", "task", "alert"]).optional().describe("Message category (default: info)")),
+            priority: s(z.number().int().min(1).max(5).optional().describe("Priority 1-5, 5=critical (default: 3)")),
+            subject: s(z.string().max(200).optional().describe("Short subject line (max 200 chars, not encrypted)")),
+            content: s(z.string().min(1).max(10_240).describe("Message body (max 10KB, encrypted at rest)")),
+            vaultId: s(z.string().uuid().optional().describe("Vault scope")),
+            expiresInDays: s(z.number().int().min(1).max(365).optional().describe("Days until expiration (default: 30)")),
+            metadata: s(z.record(z.string(), z.unknown()).optional().describe("Arbitrary metadata")),
+            template: s(z.enum(["task_assignment", "status_update", "alert", "question"]).optional().describe("Message template type for structured rendering")),
+            templateData: s(z.record(z.string(), z.unknown()).optional().describe("Template-specific data (task, deadline, severity, etc.)")),
+            parentMessageId: s(z.string().uuid().optional().describe("Reply to a specific message (creates/joins a thread)")),
+        },
+    }, auto.wrap(wrapToolHandler(async (args) => {
+        const input = args;
+        const senderId = gwAgentLabel ?? gwAgentType ?? "mcp_stdio";
+        if (gw) {
+            return await gw.sendMessage({ ...input, vaultId: resolveVault(input.vaultId) });
+        }
+        return await sendMessage(ctx, { ...input, senderId, vaultId: resolveVaultId(ctx, input.vaultId) });
+    })));
+    // ─── ack_message ──────────────────────────────────────────────────────────
+    server.registerTool("ack_message", {
+        description: "Acknowledge a received message, marking it as processed. " +
+            "Call this after acting on a directive, answering a question, or completing a task request.",
+        inputSchema: {
+            messageId: s(z.string().uuid().describe("The message ID to acknowledge")),
+        },
+    }, auto.wrap(wrapToolHandler(async (args) => {
+        const { messageId } = args;
+        if (gw) {
+            return await gw.ackMessage(messageId);
+        }
+        return await ackMessage(ctx, { messageId });
+    })));
+    // ─── read_messages ────────────────────────────────────────────────────────
+    server.registerTool("read_messages", {
+        description: "Read messages in your inbox. Returns decrypted messages sorted by priority (highest first). " +
+            "Pending messages are automatically marked as delivered. " +
+            "Use status filter to see previously delivered or acknowledged messages.",
+        inputSchema: {
+            status: s(z.enum(["pending", "delivered", "acknowledged"]).optional().describe("Filter by status (default: pending)")),
+            category: s(z.enum(["directive", "question", "info", "task", "alert"]).optional().describe("Filter by category")),
+            limit: s(z.number().int().min(1).max(50).optional().describe("Max messages to return (default: 20)")),
+            includeBroadcast: s(z.boolean().optional().describe("Include broadcast messages (default: true)")),
+            vaultId: s(z.string().uuid().optional().describe("Vault scope")),
+        },
+    }, auto.wrap(wrapToolHandler(async (args) => {
+        const input = args;
+        const agentId = gwAgentLabel ?? gwAgentType ?? "mcp_stdio";
+        if (gw) {
+            return await gw.readMessages({ ...input, vaultId: resolveVault(input.vaultId) });
+        }
+        return await readMessages(ctx, { ...input, agentId, vaultId: resolveVaultId(ctx, input.vaultId) });
+    })));
+    // ─── Orphan recovery — flush crashed sessions from previous runs ─────────
+    try {
+        const orphans = await scanOrphanedBuffers(10);
+        for (const orphan of orphans) {
+            process.stderr.write(`[exovault-mcp] Recovering orphaned session: ${orphan.agentRunId}\n`);
+            try {
+                const checkpointFn = async (params) => {
+                    if (gw) {
+                        return await gw.contextCheckpoint({
+                            ...params,
+                            vaultId: resolveVault(params.vaultId),
+                        });
+                    }
+                    return await contextCheckpoint(ctx, {
+                        ...params,
+                        vaultId: resolveVaultId(ctx, params.vaultId),
+                    });
+                };
+                await flushSession(orphan, {
+                    checkpointed: false,
+                    minToolCalls: 5,
+                    skipIfMemoriesWritten: 3,
+                    checkpointFn,
+                    agentRunId: orphan.agentRunId,
+                    agentId: orphan.agentId,
+                    vaultId: orphan.vaultId,
+                    extractionClient,
+                    readBudget,
+                    writeBudget,
+                });
+                await deleteBufferFile(orphan.agentRunId);
+                process.stderr.write(`[exovault-mcp] Orphan recovery complete: ${orphan.agentRunId}\n`);
+            }
+            catch (e) {
+                process.stderr.write(`[exovault-mcp] Orphan recovery failed for ${orphan.agentRunId}: ${e.message}\n`);
+                // Delete the buffer anyway to avoid infinite retry loops
+                await deleteBufferFile(orphan.agentRunId).catch(() => { });
+            }
+        }
+    }
+    catch (e) {
+        process.stderr.write(`[exovault-mcp] Orphan scan failed: ${e.message}\n`);
+    }
+    // ─── Start server ─────────────────────────────────────────────────────────
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    process.stderr.write("ExoVault MCP server ready\n");
+    // ─── Session lifecycle: signal handlers + stdin EOF ─────────────────────
+    // Layer 1: stdin EOF — client disconnected (IDE closed, Ctrl+C on client)
+    // The MCP SDK does NOT listen for stdin 'end', so we add it ourselves.
+    process.stdin.on("end", () => {
+        process.stderr.write("[exovault-mcp] stdin EOF detected — client disconnected\n");
+        lifecycle.flush("stdin_eof").finally(() => {
+            lifecycle.dispose();
+            process.exit(0);
+        });
+    });
+    // Layer 3: Signal handlers — OS-level kill signals
+    const handleSignal = (signal) => {
+        process.stderr.write(`[exovault-mcp] ${signal} received — flushing session\n`);
+        lifecycle.flush(signal.toLowerCase()).finally(() => {
+            lifecycle.dispose();
+            process.exit(0);
+        });
+    };
+    process.on("SIGTERM", () => handleSignal("SIGTERM"));
+    process.on("SIGINT", () => handleSignal("SIGINT"));
+}
+main().catch((err) => {
+    process.stderr.write(`Fatal: ${err.message}\n`);
+    process.exit(1);
+});