@olivaresai/alma-mcp 1.3.0

package/dist/index.js

@@ -0,0 +1,1548 @@
+#!/usr/bin/env node
+
+// src/index.ts
+import { McpServer, ResourceTemplate } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+
+// src/config.ts
+function loadConfig() {
+  const baseUrl = process.env.ALMA_API_URL ?? process.env.ALMA_BASE_URL ?? "https://alma.olivares.ai/api/v1";
+  const apiKey = process.env.ALMA_API_KEY ?? "";
+  if (!apiKey) {
+    console.error("[alma-mcp] ALMA_API_KEY environment variable is required.");
+    process.exit(1);
+  }
+  const environmentId = process.env.ALMA_ENVIRONMENT_ID || void 0;
+  const cleanUrl = baseUrl.replace(/\/+$/, "");
+  if (!cleanUrl.startsWith("https://") && !cleanUrl.startsWith("http://localhost") && !cleanUrl.startsWith("http://127.") && !cleanUrl.startsWith("http://[::1]")) {
+    console.error("[alma-mcp] ALMA_API_URL must use HTTPS for non-localhost connections. Got:", cleanUrl);
+    process.exit(1);
+  }
+  return { baseUrl: cleanUrl, apiKey, environmentId };
+}
+
+// src/client.ts
+var AlmaClient = class _AlmaClient {
+  constructor(config2) {
+    this.config = config2;
+  }
+  static DEFAULT_TIMEOUT_MS = 3e4;
+  static STREAM_TIMEOUT_MS = 6e4;
+  static MAX_RETRIES = 2;
+  static RETRYABLE_STATUS = /* @__PURE__ */ new Set([429, 502, 503, 504]);
+  headers() {
+    return {
+      "Content-Type": "application/json",
+      "X-API-Key": this.config.apiKey
+    };
+  }
+  /**
+   * Fetch with timeout and retry (exponential backoff).
+   * Retries on network errors and 502/503/504. Never retries 4xx.
+   */
+  async fetchWithRetry(url, init, timeoutMs = _AlmaClient.DEFAULT_TIMEOUT_MS) {
+    let lastError;
+    for (let attempt = 0; attempt <= _AlmaClient.MAX_RETRIES; attempt++) {
+      if (attempt > 0) {
+        const delayMs = 1e3 * 2 ** (attempt - 1);
+        await new Promise((r) => setTimeout(r, delayMs));
+      }
+      const controller = new AbortController();
+      const timer = setTimeout(() => controller.abort(), timeoutMs);
+      try {
+        const res = await fetch(url, { ...init, signal: controller.signal });
+        if (res.status === 429 && attempt < _AlmaClient.MAX_RETRIES) {
+          const retryAfter = parseInt(res.headers.get("Retry-After") || "5", 10);
+          const delayMs = Math.min(retryAfter * 1e3, 3e4);
+          await new Promise((r) => setTimeout(r, delayMs));
+          lastError = new Error(`HTTP 429 Too Many Requests`);
+          continue;
+        }
+        if (res.status >= 400 && res.status < 500) return res;
+        if (_AlmaClient.RETRYABLE_STATUS.has(res.status) && attempt < _AlmaClient.MAX_RETRIES) {
+          lastError = new Error(`HTTP ${res.status}`);
+          continue;
+        }
+        return res;
+      } catch (err) {
+        lastError = err;
+        if (attempt >= _AlmaClient.MAX_RETRIES) break;
+      } finally {
+        clearTimeout(timer);
+      }
+    }
+    throw lastError;
+  }
+  async request(method, path, body) {
+    const url = `${this.config.baseUrl}${path}`;
+    const res = await this.fetchWithRetry(url, {
+      method,
+      headers: this.headers(),
+      body: body ? JSON.stringify(body) : void 0
+    });
+    if (!res.ok) {
+      const text = await res.text().catch(() => "");
+      let detail = text;
+      try {
+        const json = JSON.parse(text);
+        detail = json.error?.message ?? json.message ?? text;
+      } catch {
+      }
+      throw new Error(`Alma API ${method} ${path} failed (${res.status}): ${detail}`);
+    }
+    return res.json();
+  }
+  // ─── Context ─────────────────────────────────────────
+  async assembleContext(params) {
+    return this.request("POST", "/context/assemble", {
+      user_message: params.message,
+      environment_id: params.environment_id ?? this.config.environmentId,
+      token_budget: params.token_budget
+    });
+  }
+  async continueSession(params) {
+    return this.request("POST", "/context/continue", {
+      ...params,
+      environment_id: params.environment_id ?? this.config.environmentId
+    });
+  }
+  async previewContext(message) {
+    return this.request("POST", "/context/preview", {
+      message
+    });
+  }
+  // ─── Memories ────────────────────────────────────────
+  async createMemory(params) {
+    return this.request("POST", "/memories", {
+      content: params.content,
+      category: params.category,
+      importance: params.importance,
+      source: params.source,
+      environment_id: params.environment_id ?? this.config.environmentId
+    });
+  }
+  async searchMemories(params) {
+    const qs = new URLSearchParams({ q: params.q });
+    if (params.limit) qs.set("limit", String(params.limit));
+    const envId = params.environment_id ?? this.config.environmentId;
+    if (envId) qs.set("environment_id", envId);
+    return this.request(
+      "GET",
+      `/memories/search?${qs}`
+    );
+  }
+  async listMemories(params) {
+    const qs = new URLSearchParams();
+    if (params?.limit != null) qs.set("limit", String(params.limit));
+    if (params?.offset != null) qs.set("offset", String(params.offset));
+    if (params?.category) qs.set("category", params.category);
+    const envId = params?.environment_id ?? this.config.environmentId;
+    if (envId) qs.set("environment_id", envId);
+    return this.request("GET", `/memories?${qs}`);
+  }
+  // ─── Extract ─────────────────────────────────────────
+  async extractMemories(params) {
+    const raw = await this.request("POST", "/memories/extract", {
+      conversation: params.text,
+      auto_save: params.save ?? true,
+      environment_id: params.environment_id ?? this.config.environmentId
+    });
+    return {
+      memories: raw.extracted.memories,
+      episode: raw.extracted.episode,
+      saved: raw.saved
+    };
+  }
+  // ─── Chat ────────────────────────────────────────────
+  async getBudget() {
+    return this.request("GET", "/chat/budget");
+  }
+  async listConversations(params) {
+    const qs = new URLSearchParams();
+    const envId = params?.environment_id ?? this.config.environmentId;
+    if (envId) qs.set("environment_id", envId);
+    if (params?.limit) qs.set("limit", String(params.limit));
+    return this.request("GET", `/chat/conversations?${qs}`);
+  }
+  async createConversation(params) {
+    return this.request("POST", "/chat/conversations", {
+      title: params?.title,
+      environment_id: params?.environment_id ?? this.config.environmentId
+    });
+  }
+  async sendMessage(conversationId, message, model) {
+    const url = `${this.config.baseUrl}/chat/conversations/${conversationId}/messages`;
+    const body = { message };
+    if (model) body.model = model;
+    const res = await this.fetchWithRetry(
+      url,
+      {
+        method: "POST",
+        headers: this.headers(),
+        body: JSON.stringify(body)
+      },
+      _AlmaClient.STREAM_TIMEOUT_MS
+    );
+    if (!res.ok) {
+      const text2 = await res.text().catch(() => "");
+      throw new Error(`Chat send failed (${res.status}): ${text2}`);
+    }
+    const text = await res.text();
+    const rawEvents = text.split("\n\n");
+    let fullContent = "";
+    for (const rawEvent of rawEvents) {
+      const dataLine = rawEvent.split("\n").find((l) => l.startsWith("data: "));
+      if (!dataLine) continue;
+      const data = dataLine.slice(6).trim();
+      if (!data) continue;
+      if (data === "[DONE]") break;
+      try {
+        const event = JSON.parse(data);
+        if (event.type === "chunk" && event.text) {
+          fullContent += event.text;
+        } else if (event.type === "done") {
+          break;
+        } else if (event.type === "error") {
+          throw new Error(event.error ?? "Chat stream error");
+        }
+      } catch (e) {
+        if (e instanceof SyntaxError) continue;
+        throw e;
+      }
+    }
+    return fullContent;
+  }
+  // ─── Soul ────────────────────────────────────────────
+  // The legacy GET /soul endpoint was removed. Soul data lives in /blocks.
+  // We fetch blocks and transform core blocks into a soul-like key/value map.
+  async getSoul() {
+    const result = await this.listBlocks();
+    const soul = {};
+    for (const block of result.blocks) {
+      if (block.value) {
+        soul[block.label] = block.value;
+      }
+    }
+    return { soul };
+  }
+  // ─── Environments ────────────────────────────────────
+  async listEnvironments() {
+    return this.request("GET", "/environments");
+  }
+  // ─── Blocks ─────────────────────────────────────────
+  async listBlocks() {
+    return this.request("GET", "/blocks");
+  }
+  // ─── Export ─────────────────────────────────────────
+  async exportData(params) {
+    let path;
+    switch (params.type) {
+      case "conversation":
+        if (!params.conversation_id) throw new Error("conversation_id is required");
+        path = `/export/conversation/${params.conversation_id}?format=${params.format ?? "md"}`;
+        break;
+      case "memories":
+        path = `/export/memories?format=${params.format ?? "json"}`;
+        break;
+      case "soul":
+        path = `/export/soul?format=${params.format ?? "json"}`;
+        break;
+      case "all":
+        path = "/export/all";
+        break;
+      default:
+        throw new Error(`Unknown export type: ${params.type}`);
+    }
+    const url = `${this.config.baseUrl}${path}`;
+    const res = await this.fetchWithRetry(url, { method: "GET", headers: this.headers() });
+    if (!res.ok) throw new Error(`Export failed (${res.status})`);
+    return res.text();
+  }
+  // ─── Block Management ──────────────────────────────
+  async updateBlock(label, value) {
+    return this.request(
+      "PUT",
+      `/blocks/${encodeURIComponent(label)}`,
+      { value }
+    );
+  }
+  // ─── Memory Management ────────────────────────────
+  async deleteMemory(id) {
+    return this.request(
+      "DELETE",
+      `/memories/${encodeURIComponent(String(id))}`
+    );
+  }
+  async updateMemory(id, params) {
+    return this.request(
+      "PUT",
+      `/memories/${encodeURIComponent(String(id))}`,
+      params
+    );
+  }
+  // ─── Image Generation ────────────────────────────
+  async generateImage(params) {
+    return this.request("POST", "/images/generate", params);
+  }
+  // ─── Environment Management ───────────────────────
+  async createEnvironment(name) {
+    return this.request("POST", "/environments", { name });
+  }
+  // ─── Context Focus ───────────────────────────────
+  async focusContext(context, source) {
+    return this.request(
+      "POST",
+      "/context/focus",
+      {
+        context,
+        source: source ?? "mcp"
+      }
+    );
+  }
+  // ─── Enhanced Search ────────────────────────────────
+  async searchMemoriesAdvanced(queryString) {
+    return this.request("GET", `/memories/search?${queryString}`);
+  }
+  // ─── Episodes ───────────────────────────────────────
+  async listEpisodes(params) {
+    const qs = new URLSearchParams();
+    if (params?.limit != null) qs.set("limit", String(params.limit));
+    if (params?.offset != null) qs.set("offset", String(params.offset));
+    return this.request("GET", `/episodes?${qs}`);
+  }
+  async searchEpisodes(params) {
+    const qs = new URLSearchParams({ topic: params.topic });
+    if (params.limit) qs.set("limit", String(params.limit));
+    return this.request("GET", `/episodes/search?${qs}`);
+  }
+  async createEpisode(params) {
+    return this.request("POST", "/episodes", params);
+  }
+  // ─── Procedures ─────────────────────────────────────
+  async listProcedures(params) {
+    const qs = new URLSearchParams();
+    if (params?.limit != null) qs.set("limit", String(params.limit));
+    if (params?.offset != null) qs.set("offset", String(params.offset));
+    return this.request("GET", `/procedures?${qs}`);
+  }
+  async createProcedure(params) {
+    return this.request("POST", "/procedures", params);
+  }
+};
+
+// src/tools/assemble.ts
+import { z } from "zod";
+function registerAssembleTool(server2, client2) {
+  server2.registerTool(
+    "alma_assemble",
+    {
+      title: "Assemble Context",
+      description: "Build a complete system prompt from Alma \u2014 includes identity (soul), relevant memories, recent episodes, and learned procedures. Use this before sending a message to an LLM to give it full context about the user.",
+      inputSchema: {
+        message: z.string().min(1).describe("The user message to assemble context for"),
+        environment_id: z.string().optional().describe("Environment ID (uses default if omitted)"),
+        token_budget: z.number().int().positive().optional().describe("Maximum token budget for the assembled context (default: 2000)")
+      }
+    },
+    async ({ message, environment_id, token_budget }) => {
+      try {
+        const result = await client2.assembleContext({
+          message,
+          environment_id,
+          token_budget
+        });
+        return {
+          content: [
+            {
+              type: "text",
+              text: result.system_prompt
+            },
+            {
+              type: "text",
+              text: `
+---
+Metadata: ${result.metadata.memoriesIncluded} memories, ${result.metadata.episodesIncluded} episodes, ${result.metadata.proceduresIncluded} procedures (${result.metadata.totalTokens} tokens)`
+            }
+          ]
+        };
+      } catch (err) {
+        const errorMessage = err instanceof Error ? err.message : "Unknown error";
+        return {
+          content: [{ type: "text", text: `Error: ${errorMessage}` }],
+          isError: true
+        };
+      }
+    }
+  );
+}
+
+// src/tools/remember.ts
+import { z as z2 } from "zod";
+function registerRememberTool(server2, client2) {
+  server2.registerTool(
+    "alma_remember",
+    {
+      title: "Remember",
+      description: "Save a new memory to Alma. Use this to store facts, preferences, decisions, or any information that should persist across conversations.",
+      inputSchema: {
+        content: z2.string().min(1).max(5e4).describe("The memory content to save"),
+        category: z2.enum(["general", "preference", "fact", "decision", "project"]).optional().describe("Category of the memory (default: general)"),
+        importance: z2.number().min(0).max(1).optional().describe("Importance from 0 to 1 (default: 0.5)")
+      }
+    },
+    async ({ content, category, importance }) => {
+      try {
+        const result = await client2.createMemory({
+          content,
+          category,
+          importance,
+          source: "mcp"
+        });
+        return {
+          content: [
+            {
+              type: "text",
+              text: `Memory saved successfully.
+${JSON.stringify(result.memory, null, 2)}`
+            }
+          ]
+        };
+      } catch (err) {
+        const message = err instanceof Error ? err.message : "Unknown error";
+        return {
+          content: [{ type: "text", text: `Error: ${message}` }],
+          isError: true
+        };
+      }
+    }
+  );
+}
+
+// src/tools/recall.ts
+import { z as z3 } from "zod";
+function registerRecallTool(server2, client2) {
+  server2.registerTool(
+    "alma_recall",
+    {
+      title: "Recall Memories",
+      description: "Search Alma memories by keyword. Returns relevant memories matching the query, ranked by relevance and importance. Use this to retrieve stored knowledge.",
+      inputSchema: {
+        query: z3.string().min(1).describe("Search query to find relevant memories"),
+        limit: z3.number().int().min(1).max(50).optional().describe("Maximum number of results (default: 10)")
+      }
+    },
+    async ({ query, limit }) => {
+      try {
+        const result = await client2.searchMemories({
+          q: query,
+          limit: limit ?? 10
+        });
+        if (result.memories.length === 0) {
+          return {
+            content: [
+              { type: "text", text: "No memories found matching the query." }
+            ]
+          };
+        }
+        const formatted = result.memories.map((m, i) => {
+          const cat = m.category ?? "unknown";
+          const imp = m.importance ?? "?";
+          return `${i + 1}. [${cat}] (importance: ${imp}) ${m.content}`;
+        }).join("\n");
+        return {
+          content: [
+            {
+              type: "text",
+              text: `Found ${result.memories.length} memories:
+
+${formatted}`
+            }
+          ]
+        };
+      } catch (err) {
+        const message = err instanceof Error ? err.message : "Unknown error";
+        return {
+          content: [{ type: "text", text: `Error: ${message}` }],
+          isError: true
+        };
+      }
+    }
+  );
+}
+
+// src/tools/extract.ts
+import { z as z4 } from "zod";
+function registerExtractTool(server2, client2) {
+  server2.registerTool(
+    "alma_extract",
+    {
+      title: "Extract Memories",
+      description: "Analyze a conversation and extract key memories, facts, and patterns using AI. Optionally saves them to Alma automatically. Use this after a conversation to capture important information.",
+      inputSchema: {
+        text: z4.string().min(10).max(2e5).describe("Conversation text to extract memories from"),
+        save: z4.boolean().optional().describe("Whether to automatically save extracted memories (default: true)"),
+        environment_id: z4.string().optional().describe("Environment ID (uses default if omitted)")
+      }
+    },
+    async ({ text, save, environment_id }) => {
+      try {
+        const result = await client2.extractMemories({
+          text,
+          save: save ?? true,
+          environment_id
+        });
+        const parts = [];
+        if (result.memories.length > 0) {
+          parts.push(`Extracted ${result.memories.length} memories:`);
+          for (const m of result.memories) {
+            parts.push(`  - [${m.category}] (importance: ${m.importance}) ${m.content}`);
+          }
+        } else {
+          parts.push("No memories extracted from the text.");
+        }
+        if (result.episode) {
+          parts.push(`
+Episode: ${result.episode.summary}`);
+          if (result.episode.topics.length > 0) {
+            parts.push(`Topics: ${result.episode.topics.join(", ")}`);
+          }
+        }
+        if (result.saved) {
+          parts.push("\nAll extracted data has been saved to Alma.");
+        }
+        return {
+          content: [{ type: "text", text: parts.join("\n") }]
+        };
+      } catch (err) {
+        const message = err instanceof Error ? err.message : "Unknown error";
+        return {
+          content: [{ type: "text", text: `Error: ${message}` }],
+          isError: true
+        };
+      }
+    }
+  );
+}
+
+// src/tools/chat.ts
+import { z as z5 } from "zod";
+function registerChatTool(server2, client2) {
+  server2.registerTool(
+    "alma_chat",
+    {
+      title: "Chat with Alma",
+      description: "Send a message to Alma's managed chat. Alma assembles context from memories, soul, and episodes, then responds via its own LLM. Creates a new conversation if conversation_id is not provided.",
+      inputSchema: {
+        message: z5.string().min(1).describe("The message to send"),
+        conversation_id: z5.string().optional().describe("Existing conversation ID. If omitted, a new conversation is created."),
+        environment_id: z5.string().optional().describe("Environment ID for new conversations (uses default if omitted)"),
+        model: z5.enum([
+          "claude-haiku",
+          "claude-sonnet",
+          "claude-opus"
+        ]).optional().describe("LLM model to use for the response. If omitted, uses the server default.")
+      }
+    },
+    async ({ message, conversation_id, environment_id, model }) => {
+      try {
+        let convId = conversation_id;
+        if (!convId) {
+          const conv = await client2.createConversation({
+            title: message.slice(0, 60),
+            environment_id
+          });
+          convId = conv.conversation.id;
+        }
+        const response = await client2.sendMessage(convId, message, model);
+        return {
+          content: [
+            {
+              type: "text",
+              text: response
+            },
+            {
+              type: "text",
+              text: `
+---
+Conversation: ${convId}${model ? ` | Model: ${model}` : ""}`
+            }
+          ]
+        };
+      } catch (err) {
+        const errMsg = err instanceof Error ? err.message : "Unknown error";
+        return {
+          content: [{ type: "text", text: `Error: ${errMsg}` }],
+          isError: true
+        };
+      }
+    }
+  );
+}
+
+// src/tools/generate-image.ts
+import { z as z6 } from "zod";
+function registerGenerateImageTool(server2, client2) {
+  server2.registerTool(
+    "alma_generate_image",
+    {
+      title: "Generate Image",
+      description: "Generate an image using Alma's Image Studio (Replicate Flux or Leonardo AI). Returns the generated image URL with metadata. Requires a paid plan.",
+      inputSchema: {
+        prompt: z6.string().min(1).max(2e3).describe("Text description of the image to generate"),
+        style: z6.enum(["natural", "vivid", "artistic"]).optional().describe("Image style (default: natural)"),
+        size: z6.enum(["square", "landscape", "portrait"]).optional().describe("Image size/aspect ratio (default: square)")
+      }
+    },
+    async ({ prompt, style, size }) => {
+      try {
+        const result = await client2.generateImage({ prompt, style, size });
+        const img = result.image;
+        return {
+          content: [
+            {
+              type: "text",
+              text: `Image generated successfully.
+
+URL: ${img.url}
+Size: ${img.width}x${img.height}
+Model: ${img.model} (${img.provider})
+Prompt: ${img.prompt}`
+            }
+          ]
+        };
+      } catch (err) {
+        const message = err instanceof Error ? err.message : "Unknown error";
+        return {
+          content: [{ type: "text", text: `Error: ${message}` }],
+          isError: true
+        };
+      }
+    }
+  );
+}
+
+// src/tools/export.ts
+import { z as z7 } from "zod";
+function registerExportTool(server2, client2) {
+  server2.registerTool(
+    "alma_export",
+    {
+      title: "Export Data",
+      description: "Export Alma data in text formats. Supported exports: conversation (md or html), memories (json or md), soul (json or md), or all (json). Binary formats (pdf, docx, xlsx) are only available via the web app.",
+      inputSchema: {
+        type: z7.enum(["conversation", "memories", "soul", "all"]).describe("What to export"),
+        format: z7.enum(["md", "json", "html"]).optional().describe('Export format. For conversation: md (default) or html. For memories/soul: json (default) or md. Ignored for "all".'),
+        conversation_id: z7.string().optional().describe('Conversation ID (required when type is "conversation")')
+      }
+    },
+    async ({ type, format, conversation_id }) => {
+      try {
+        if (type === "conversation" && format && !["md", "html"].includes(format)) {
+          return {
+            content: [{ type: "text", text: 'Error: Conversation export supports "md" or "html" format only.' }],
+            isError: true
+          };
+        }
+        if ((type === "memories" || type === "soul") && format && !["json", "md"].includes(format)) {
+          return {
+            content: [{ type: "text", text: `Error: ${type} export supports "json" or "md" format only.` }],
+            isError: true
+          };
+        }
+        const result = await client2.exportData({ type, format, conversation_id });
+        return {
+          content: [
+            {
+              type: "text",
+              text: result
+            }
+          ]
+        };
+      } catch (err) {
+        const message = err instanceof Error ? err.message : "Unknown error";
+        return {
+          content: [{ type: "text", text: `Error: ${message}` }],
+          isError: true
+        };
+      }
+    }
+  );
+}
+
+// src/tools/search.ts
+import { z as z8 } from "zod";
+function registerSearchTool(server2, client2) {
+  server2.registerTool(
+    "alma_search",
+    {
+      title: "Enhanced Search",
+      description: "Search Alma memories with advanced filters: date range, category, importance threshold, and search mode (keyword, semantic, or hybrid). More powerful than basic recall.",
+      inputSchema: {
+        query: z8.string().min(1).describe("Search query"),
+        mode: z8.enum(["keyword", "semantic", "hybrid"]).optional().describe("Search mode (default: keyword)"),
+        from: z8.string().optional().describe("Start date filter (ISO format, e.g. 2025-01-01)"),
+        to: z8.string().optional().describe("End date filter (ISO format)"),
+        category: z8.enum(["general", "preference", "fact", "decision", "project"]).optional().describe("Filter by memory category"),
+        min_importance: z8.number().min(0).max(1).optional().describe("Minimum importance threshold (0-1)"),
+        limit: z8.number().int().min(1).max(50).optional().describe("Maximum results (default: 20)")
+      }
+    },
+    async ({ query, mode, from, to, category, min_importance, limit }) => {
+      try {
+        const qs = new URLSearchParams({ q: query });
+        if (mode) qs.set("mode", mode);
+        if (from) qs.set("from", from);
+        if (to) qs.set("to", to);
+        if (category) qs.set("category", category);
+        if (min_importance !== void 0) qs.set("min_importance", String(min_importance));
+        if (limit) qs.set("limit", String(limit));
+        const result = await client2.searchMemoriesAdvanced(qs.toString());
+        if (result.memories.length === 0) {
+          return {
+            content: [
+              { type: "text", text: "No memories found matching the search criteria." }
+            ]
+          };
+        }
+        const formatted = result.memories.map((m, i) => {
+          const score = m.score ? ` (score: ${m.score.toFixed(3)})` : "";
+          return `${i + 1}. [${m.category}] (importance: ${m.importance})${score} ${m.content}`;
+        }).join("\n");
+        return {
+          content: [
+            {
+              type: "text",
+              text: `Found ${result.memories.length} memories (mode: ${mode ?? "keyword"}):
+
+${formatted}`
+            }
+          ]
+        };
+      } catch (err) {
+        const message = err instanceof Error ? err.message : "Unknown error";
+        return {
+          content: [{ type: "text", text: `Error: ${message}` }],
+          isError: true
+        };
+      }
+    }
+  );
+}
+
+// src/tools/update-block.ts
+import { z as z9 } from "zod";
+function registerUpdateBlockTool(server2, client2) {
+  server2.registerTool(
+    "alma_update_block",
+    {
+      title: "Update Block",
+      description: "Update a memory block value (e.g. identity, rules, language, user_profile, active_context, learned_patterns, scratchpad). Use this to modify Alma's personality and behavior configuration.",
+      inputSchema: {
+        label: z9.string().min(1).describe('The block label to update (e.g. "identity", "rules", "language", "user_profile")'),
+        value: z9.string().min(1).describe("The new value for the block")
+      }
+    },
+    async ({ label, value }) => {
+      try {
+        const result = await client2.updateBlock(label, value);
+        return {
+          content: [
+            {
+              type: "text",
+              text: `Block "${label}" updated successfully.
+${JSON.stringify(result.block, null, 2)}`
+            }
+          ]
+        };
+      } catch (err) {
+        const message = err instanceof Error ? err.message : "Unknown error";
+        return {
+          content: [{ type: "text", text: `Error: ${message}` }],
+          isError: true
+        };
+      }
+    }
+  );
+}
+
+// src/tools/manage-memory.ts
+import { z as z10 } from "zod";
+function registerDeleteMemoryTool(server2, client2) {
+  server2.registerTool(
+    "alma_delete_memory",
+    {
+      title: "Delete Memory",
+      description: "Delete a specific memory by its ID. Use alma_recall or alma_search first to find the memory ID.",
+      inputSchema: {
+        id: z10.string().min(1).regex(/^\d+$/, "Memory ID must be numeric").describe("The memory ID to delete")
+      }
+    },
+    async ({ id }) => {
+      try {
+        await client2.deleteMemory(Number(id));
+        return {
+          content: [
+            {
+              type: "text",
+              text: `Memory ${id} deleted successfully.`
+            }
+          ]
+        };
+      } catch (err) {
+        const message = err instanceof Error ? err.message : "Unknown error";
+        return {
+          content: [{ type: "text", text: `Error: ${message}` }],
+          isError: true
+        };
+      }
+    }
+  );
+}
+
+// src/tools/environment.ts
+import { z as z11 } from "zod";
+function registerCreateEnvironmentTool(server2, client2) {
+  server2.registerTool(
+    "alma_create_environment",
+    {
+      title: "Create Environment",
+      description: "Create a new Alma environment. Environments isolate soul configuration, memories, and conversations for different projects or contexts.",
+      inputSchema: {
+        name: z11.string().min(1).max(100).describe('Name for the new environment (e.g. "Work Project", "Personal")')
+      }
+    },
+    async ({ name }) => {
+      try {
+        const result = await client2.createEnvironment(name);
+        return {
+          content: [
+            {
+              type: "text",
+              text: `Environment created successfully.
+${JSON.stringify(result.environment, null, 2)}`
+            }
+          ]
+        };
+      } catch (err) {
+        const message = err instanceof Error ? err.message : "Unknown error";
+        return {
+          content: [{ type: "text", text: `Error: ${message}` }],
+          isError: true
+        };
+      }
+    }
+  );
+}
+function registerListEnvironmentsTool(server2, client2) {
+  server2.registerTool(
+    "alma_list_environments",
+    {
+      title: "List Environments",
+      description: "List available environments. Use the returned environment IDs to scope subsequent tool calls with the environment_id parameter.",
+      inputSchema: {}
+    },
+    async () => {
+      try {
+        const result = await client2.listEnvironments();
+        const envList = result.environments.map((e) => `- ${e.name} (${e.id})${e.is_default ? " [default]" : ""}`).join("\n");
+        return {
+          content: [
+            {
+              type: "text",
+              text: `Available environments:
+${envList}
+
+Use the environment_id parameter in other tools to work within a specific environment.`
+            }
+          ]
+        };
+      } catch (err) {
+        const message = err instanceof Error ? err.message : "Unknown error";
+        return {
+          content: [{ type: "text", text: `Error: ${message}` }],
+          isError: true
+        };
+      }
+    }
+  );
+}
+
+// src/tools/focus.ts
+import { z as z12 } from "zod";
+function registerFocusTool(server2, client2) {
+  server2.registerTool(
+    "alma_focus",
+    {
+      title: "Set Context Focus",
+      description: "Update Alma's active context with what you're currently working on. This helps Alma provide more relevant responses by knowing your current focus (e.g. project name, file, task).",
+      inputSchema: {
+        context: z12.string().min(1).max(2e3).describe('Description of the current focus/context (e.g. "Working on auth module in project-x", "Reviewing PR #42")'),
+        source: z12.enum(["web", "extension", "mcp", "api"]).optional().describe('Source identifier (default: "mcp")')
+      }
+    },
+    async ({ context, source }) => {
+      try {
+        await client2.focusContext(context, source);
+        return {
+          content: [
+            {
+              type: "text",
+              text: `Context focus updated: "${context}"`
+            }
+          ]
+        };
+      } catch (err) {
+        const message = err instanceof Error ? err.message : "Unknown error";
+        return {
+          content: [{ type: "text", text: `Error: ${message}` }],
+          isError: true
+        };
+      }
+    }
+  );
+}
+
+// src/tools/continue-session.ts
+import { z as z13 } from "zod";
+function registerContinueSessionTool(server2, client2) {
+  server2.registerTool(
+    "alma_continue_session",
+    {
+      title: "Continue Session",
+      description: "Generate a session continuation summary when hitting context limits or starting a new session. Returns a structured summary with active tasks, key decisions, and a continuation prompt.",
+      inputSchema: {
+        conversation_text: z13.string().min(1).describe("The conversation text to summarize for continuation"),
+        reason: z13.enum(["context_limit", "new_session", "error"]).describe("Why the session is being continued"),
+        environment_id: z13.string().optional().describe("Environment ID to scope the continuation")
+      }
+    },
+    async ({ conversation_text, reason, environment_id }) => {
+      try {
+        const result = await client2.continueSession({
+          conversation_text,
+          reason,
+          environment_id
+        });
+        return {
+          content: [
+            {
+              type: "text",
+              text: [
+                "## Session Summary",
+                result.session_summary,
+                "",
+                "## Active Tasks",
+                ...result.active_tasks.map((t) => `- ${t}`),
+                "",
+                "## Key Decisions",
+                ...result.key_decisions.map((d) => `- ${d}`),
+                "",
+                "## Pending Items",
+                ...result.pending_items.map((p) => `- ${p}`),
+                "",
+                "## Continuation Prompt",
+                result.continuation_prompt
+              ].join("\n")
+            }
+          ]
+        };
+      } catch (err) {
+        const message = err instanceof Error ? err.message : "Unknown error";
+        return {
+          content: [{ type: "text", text: `Error: ${message}` }],
+          isError: true
+        };
+      }
+    }
+  );
+}
+
+// src/tools/episodes.ts
+import { z as z14 } from "zod";
+function registerListEpisodesTool(server2, client2) {
+  server2.registerTool(
+    "alma_list_episodes",
+    {
+      title: "List Episodes",
+      description: "List recent episodes (conversation summaries with topics and outcomes). Episodes capture what happened in past conversations.",
+      inputSchema: {
+        limit: z14.number().int().min(1).max(100).optional().describe("Maximum number of episodes to return (default: 20)"),
+        offset: z14.number().int().min(0).optional().describe("Number of episodes to skip (default: 0)")
+      }
+    },
+    async ({ limit, offset }) => {
+      try {
+        const result = await client2.listEpisodes({ limit, offset });
+        if (result.episodes.length === 0) {
+          return {
+            content: [{ type: "text", text: "No episodes found." }]
+          };
+        }
+        return {
+          content: [
+            {
+              type: "text",
+              text: JSON.stringify(result, null, 2)
+            }
+          ]
+        };
+      } catch (err) {
+        const message = err instanceof Error ? err.message : "Unknown error";
+        return {
+          content: [{ type: "text", text: `Error: ${message}` }],
+          isError: true
+        };
+      }
+    }
+  );
+}
+function registerSearchEpisodesTool(server2, client2) {
+  server2.registerTool(
+    "alma_search_episodes",
+    {
+      title: "Search Episodes",
+      description: "Search episodes by topic. Returns episodes that match the given topic keyword.",
+      inputSchema: {
+        topic: z14.string().min(1).describe("Topic keyword to search for"),
+        limit: z14.number().int().min(1).max(50).optional().describe("Maximum number of results (default: 10)")
+      }
+    },
+    async ({ topic, limit }) => {
+      try {
+        const result = await client2.searchEpisodes({ topic, limit });
+        if (result.episodes.length === 0) {
+          return {
+            content: [{ type: "text", text: `No episodes found for topic: ${topic}` }]
+          };
+        }
+        return {
+          content: [
+            {
+              type: "text",
+              text: JSON.stringify(result, null, 2)
+            }
+          ]
+        };
+      } catch (err) {
+        const message = err instanceof Error ? err.message : "Unknown error";
+        return {
+          content: [{ type: "text", text: `Error: ${message}` }],
+          isError: true
+        };
+      }
+    }
+  );
+}
+function registerCreateEpisodeTool(server2, client2) {
+  server2.registerTool(
+    "alma_create_episode",
+    {
+      title: "Create Episode",
+      description: "Create a new episode (conversation summary). Episodes capture what happened, what topics were discussed, and the outcome.",
+      inputSchema: {
+        summary: z14.string().min(1).max(5e3).describe("Summary of what happened in the conversation"),
+        topics: z14.array(z14.string()).optional().describe("List of topics discussed"),
+        outcome: z14.string().optional().describe("Outcome or result of the conversation")
+      }
+    },
+    async ({ summary, topics, outcome }) => {
+      try {
+        const result = await client2.createEpisode({ summary, topics, outcome });
+        return {
+          content: [
+            {
+              type: "text",
+              text: `Episode created successfully.
+${JSON.stringify(result, null, 2)}`
+            }
+          ]
+        };
+      } catch (err) {
+        const message = err instanceof Error ? err.message : "Unknown error";
+        return {
+          content: [{ type: "text", text: `Error: ${message}` }],
+          isError: true
+        };
+      }
+    }
+  );
+}
+
+// src/tools/procedures.ts
+import { z as z15 } from "zod";
+function registerListProceduresTool(server2, client2) {
+  server2.registerTool(
+    "alma_list_procedures",
+    {
+      title: "List Procedures",
+      description: "List stored procedures. Procedures are trigger-action rules that Alma follows when certain patterns are detected in conversations.",
+      inputSchema: {
+        limit: z15.number().int().min(1).max(100).optional().describe("Maximum number of procedures to return (default: 50)"),
+        offset: z15.number().int().min(0).optional().describe("Number of procedures to skip (default: 0)")
+      }
+    },
+    async ({ limit, offset }) => {
+      try {
+        const result = await client2.listProcedures({ limit, offset });
+        if (result.procedures.length === 0) {
+          return {
+            content: [{ type: "text", text: "No procedures found." }]
+          };
+        }
+        return {
+          content: [
+            {
+              type: "text",
+              text: JSON.stringify(result, null, 2)
+            }
+          ]
+        };
+      } catch (err) {
+        const message = err instanceof Error ? err.message : "Unknown error";
+        return {
+          content: [{ type: "text", text: `Error: ${message}` }],
+          isError: true
+        };
+      }
+    }
+  );
+}
+function registerCreateProcedureTool(server2, client2) {
+  server2.registerTool(
+    "alma_create_procedure",
+    {
+      title: "Create Procedure",
+      description: "Create a new procedure (trigger-action rule). Procedures define automated behaviors: when a trigger pattern is detected, the specified action is taken.",
+      inputSchema: {
+        trigger_pattern: z15.string().min(1).describe("The pattern or condition that triggers this procedure"),
+        action: z15.string().min(1).describe("The action to take when the trigger is detected"),
+        context: z15.string().optional().describe("Additional context or conditions for the procedure")
+      }
+    },
+    async ({ trigger_pattern, action, context }) => {
+      try {
+        const result = await client2.createProcedure({ trigger_pattern, action, context });
+        return {
+          content: [
+            {
+              type: "text",
+              text: `Procedure created successfully.
+${JSON.stringify(result, null, 2)}`
+            }
+          ]
+        };
+      } catch (err) {
+        const message = err instanceof Error ? err.message : "Unknown error";
+        return {
+          content: [{ type: "text", text: `Error: ${message}` }],
+          isError: true
+        };
+      }
+    }
+  );
+}
+
+// src/tools/preview-context.ts
+import { z as z16 } from "zod";
+function registerPreviewContextTool(server2, client2) {
+  server2.registerTool(
+    "alma_preview_context",
+    {
+      title: "Preview Context",
+      description: "Preview the full system prompt that Alma would assemble for a given message. Shows exactly what the LLM sees, including identity, memories, episodes, and procedures. Useful for debugging and understanding context assembly.",
+      inputSchema: {
+        message: z16.string().optional().describe("Optional message to simulate context assembly for. If omitted, shows the default context.")
+      }
+    },
+    async ({ message }) => {
+      try {
+        const result = await client2.previewContext(message);
+        const metaSummary = result.metadata ? `
+
+--- Metadata ---
+Soul tokens: ${result.metadata.soulTokens}
+Memories: ${result.metadata.memoriesIncluded} (${result.metadata.memoriesTokens} tokens)
+Episodes: ${result.metadata.episodesIncluded} (${result.metadata.episodesTokens} tokens)
+Procedures: ${result.metadata.proceduresIncluded} (${result.metadata.proceduresTokens} tokens)
+Total tokens: ${result.metadata.totalTokens}` : "";
+        return {
+          content: [
+            {
+              type: "text",
+              text: `${result.system_prompt}${metaSummary}`
+            }
+          ]
+        };
+      } catch (err) {
+        const errorMessage = err instanceof Error ? err.message : "Unknown error";
+        return {
+          content: [{ type: "text", text: `Error: ${errorMessage}` }],
+          isError: true
+        };
+      }
+    }
+  );
+}
+
+// src/tools/update-memory.ts
+import { z as z17 } from "zod";
+function registerUpdateMemoryTool(server2, client2) {
+  server2.registerTool(
+    "alma_update_memory",
+    {
+      title: "Update Memory",
+      description: "Update an existing memory in Alma. Can modify the content, category, or importance. At least one field must be provided.",
+      inputSchema: {
+        id: z17.number().int().positive().describe("The memory ID to update"),
+        content: z17.string().min(1).max(5e4).optional().describe("New content for the memory"),
+        category: z17.enum(["general", "preference", "fact", "decision", "project"]).optional().describe("New category for the memory"),
+        importance: z17.number().min(0).max(1).optional().describe("New importance score (0 to 1)")
+      }
+    },
+    async ({ id, content, category, importance }) => {
+      try {
+        if (content === void 0 && category === void 0 && importance === void 0) {
+          return {
+            content: [{ type: "text", text: "Error: At least one of content, category, or importance must be provided." }],
+            isError: true
+          };
+        }
+        const params = {};
+        if (content !== void 0) params.content = content;
+        if (category !== void 0) params.category = category;
+        if (importance !== void 0) params.importance = importance;
+        const result = await client2.updateMemory(id, params);
+        return {
+          content: [
+            {
+              type: "text",
+              text: `Memory ${id} updated successfully.
+${JSON.stringify(result.memory, null, 2)}`
+            }
+          ]
+        };
+      } catch (err) {
+        const message = err instanceof Error ? err.message : "Unknown error";
+        return {
+          content: [{ type: "text", text: `Error: ${message}` }],
+          isError: true
+        };
+      }
+    }
+  );
+}
+
+// src/index.ts
+var config = loadConfig();
+var client = new AlmaClient(config);
+var server = new McpServer({
+  name: "alma-mcp",
+  version: "1.3.0"
+});
+registerAssembleTool(server, client);
+registerRememberTool(server, client);
+registerRecallTool(server, client);
+registerExtractTool(server, client);
+registerChatTool(server, client);
+registerGenerateImageTool(server, client);
+registerExportTool(server, client);
+registerSearchTool(server, client);
+registerUpdateBlockTool(server, client);
+registerDeleteMemoryTool(server, client);
+registerCreateEnvironmentTool(server, client);
+registerListEnvironmentsTool(server, client);
+registerFocusTool(server, client);
+registerContinueSessionTool(server, client);
+registerListEpisodesTool(server, client);
+registerSearchEpisodesTool(server, client);
+registerCreateEpisodeTool(server, client);
+registerListProceduresTool(server, client);
+registerCreateProcedureTool(server, client);
+registerPreviewContextTool(server, client);
+registerUpdateMemoryTool(server, client);
+server.registerResource(
+  "soul",
+  "alma://soul",
+  {
+    title: "Alma Soul",
+    description: "The current soul configuration (identity, personality, tone, rules)",
+    mimeType: "application/json"
+  },
+  async (uri) => {
+    try {
+      const result = await client.getSoul();
+      return {
+        contents: [
+          {
+            uri: uri.href,
+            mimeType: "application/json",
+            text: JSON.stringify(result.soul, null, 2)
+          }
+        ]
+      };
+    } catch (err) {
+      const message = err instanceof Error ? err.message : "Unknown error";
+      return {
+        contents: [{ uri: uri.href, mimeType: "text/plain", text: `Error loading resource: ${message}` }]
+      };
+    }
+  }
+);
+server.registerResource(
+  "memories",
+  "alma://memories",
+  {
+    title: "Alma Memories",
+    description: "Recent memories stored in Alma (last 50)",
+    mimeType: "application/json"
+  },
+  async (uri) => {
+    try {
+      const result = await client.listMemories({ limit: 50 });
+      return {
+        contents: [
+          {
+            uri: uri.href,
+            mimeType: "application/json",
+            text: JSON.stringify(result.memories, null, 2)
+          }
+        ]
+      };
+    } catch (err) {
+      const message = err instanceof Error ? err.message : "Unknown error";
+      return {
+        contents: [{ uri: uri.href, mimeType: "text/plain", text: `Error loading resource: ${message}` }]
+      };
+    }
+  }
+);
+server.registerResource(
+  "environments",
+  "alma://environments",
+  {
+    title: "Alma Environments",
+    description: "All environments (Alma instances) available to the user",
+    mimeType: "application/json"
+  },
+  async (uri) => {
+    try {
+      const result = await client.listEnvironments();
+      return {
+        contents: [
+          {
+            uri: uri.href,
+            mimeType: "application/json",
+            text: JSON.stringify(result.environments, null, 2)
+          }
+        ]
+      };
+    } catch (err) {
+      const message = err instanceof Error ? err.message : "Unknown error";
+      return {
+        contents: [{ uri: uri.href, mimeType: "text/plain", text: `Error loading resource: ${message}` }]
+      };
+    }
+  }
+);
+server.registerResource(
+  "conversations",
+  "alma://conversations",
+  {
+    title: "Alma Conversations",
+    description: "Recent chat conversations",
+    mimeType: "application/json"
+  },
+  async (uri) => {
+    try {
+      const result = await client.listConversations({ limit: 20 });
+      return {
+        contents: [
+          {
+            uri: uri.href,
+            mimeType: "application/json",
+            text: JSON.stringify(result.conversations, null, 2)
+          }
+        ]
+      };
+    } catch (err) {
+      const message = err instanceof Error ? err.message : "Unknown error";
+      return {
+        contents: [{ uri: uri.href, mimeType: "text/plain", text: `Error loading resource: ${message}` }]
+      };
+    }
+  }
+);
+server.registerResource(
+  "budget",
+  "alma://budget",
+  {
+    title: "Token Budget",
+    description: "Current token budget status (weekly usage, remaining, purchased)",
+    mimeType: "application/json"
+  },
+  async (uri) => {
+    try {
+      const result = await client.getBudget();
+      return {
+        contents: [
+          {
+            uri: uri.href,
+            mimeType: "application/json",
+            text: JSON.stringify(result, null, 2)
+          }
+        ]
+      };
+    } catch (err) {
+      const message = err instanceof Error ? err.message : "Unknown error";
+      return {
+        contents: [{ uri: uri.href, mimeType: "text/plain", text: `Error loading resource: ${message}` }]
+      };
+    }
+  }
+);
+server.registerResource(
+  "memories-by-category",
+  new ResourceTemplate("alma://memories/{category}", {
+    list: async () => ({
+      resources: [
+        { uri: "alma://memories/general", name: "General" },
+        { uri: "alma://memories/preference", name: "Preferences" },
+        { uri: "alma://memories/fact", name: "Facts" },
+        { uri: "alma://memories/decision", name: "Decisions" },
+        { uri: "alma://memories/project", name: "Projects" }
+      ]
+    })
+  }),
+  {
+    title: "Memories by Category",
+    description: "Alma memories filtered by category",
+    mimeType: "application/json"
+  },
+  async (uri, { category }) => {
+    try {
+      const cat = Array.isArray(category) ? category[0] : category;
+      const result = await client.listMemories({ category: cat, limit: 50 });
+      return {
+        contents: [
+          {
+            uri: uri.href,
+            mimeType: "application/json",
+            text: JSON.stringify(result.memories, null, 2)
+          }
+        ]
+      };
+    } catch (err) {
+      const message = err instanceof Error ? err.message : "Unknown error";
+      return {
+        contents: [{ uri: uri.href, mimeType: "text/plain", text: `Error loading resource: ${message}` }]
+      };
+    }
+  }
+);
+server.registerResource(
+  "blocks",
+  "alma://blocks",
+  {
+    title: "Memory Blocks",
+    description: "All memory blocks (identity, worldview, style, rules, etc.)",
+    mimeType: "application/json"
+  },
+  async (uri) => {
+    try {
+      const result = await client.listBlocks();
+      return {
+        contents: [
+          {
+            uri: uri.href,
+            mimeType: "application/json",
+            text: JSON.stringify(result.blocks, null, 2)
+          }
+        ]
+      };
+    } catch (err) {
+      const message = err instanceof Error ? err.message : "Unknown error";
+      return {
+        contents: [{ uri: uri.href, mimeType: "text/plain", text: `Error loading resource: ${message}` }]
+      };
+    }
+  }
+);
+server.registerResource(
+  "episodes",
+  "alma://episodes",
+  {
+    title: "Alma Episodes",
+    description: "Recent episodes \u2014 conversation summaries with topics and outcomes (last 20)",
+    mimeType: "application/json"
+  },
+  async (uri) => {
+    try {
+      const result = await client.listEpisodes({ limit: 20 });
+      return {
+        contents: [
+          {
+            uri: uri.href,
+            mimeType: "application/json",
+            text: JSON.stringify(result.episodes, null, 2)
+          }
+        ]
+      };
+    } catch (err) {
+      const message = err instanceof Error ? err.message : "Unknown error";
+      return {
+        contents: [{ uri: uri.href, mimeType: "text/plain", text: `Error loading resource: ${message}` }]
+      };
+    }
+  }
+);
+server.registerResource(
+  "procedures",
+  "alma://procedures",
+  {
+    title: "Alma Procedures",
+    description: "All stored procedures \u2014 trigger-action rules that Alma follows (limit 50)",
+    mimeType: "application/json"
+  },
+  async (uri) => {
+    try {
+      const result = await client.listProcedures({ limit: 50 });
+      return {
+        contents: [
+          {
+            uri: uri.href,
+            mimeType: "application/json",
+            text: JSON.stringify(result.procedures, null, 2)
+          }
+        ]
+      };
+    } catch (err) {
+      const message = err instanceof Error ? err.message : "Unknown error";
+      return {
+        contents: [{ uri: uri.href, mimeType: "text/plain", text: `Error loading resource: ${message}` }]
+      };
+    }
+  }
+);
+async function main() {
+  const transport = new StdioServerTransport();
+  await server.connect(transport);
+  console.error("[alma-mcp] Server started on stdio (v1.3.0, 21 tools, 9 resources)");
+  if (process.env.ALMA_DEBUG) {
+    console.error(`[alma-mcp] API: ${config.baseUrl}`);
+    if (config.environmentId) {
+      console.error(`[alma-mcp] Environment: ${config.environmentId}`);
+    }
+  }
+}
+var shutdown = () => {
+  console.error("[alma-mcp] Shutting down...");
+  server.close().catch(() => {
+  });
+  process.exit(0);
+};
+process.on("SIGTERM", shutdown);
+process.on("SIGINT", shutdown);
+main().catch((err) => {
+  console.error("[alma-mcp] Fatal error:", err);
+  process.exit(1);
+});