@memoryrelay/mcp-server 0.1.9 → 0.3.0

package/dist/index.js

@@ -1,356 +1,25 @@
 #!/usr/bin/env node
-
-// src/config.ts
-import { z } from "zod";
-var configSchema = z.object({
-  apiKey: z.string().startsWith("mem_", { message: 'API key must start with "mem_"' }).min(20, { message: "API key appears to be invalid (too short)" }),
-  apiUrl: z.string().url({ message: "API URL must be a valid URL" }).default("https://api.memoryrelay.net"),
-  agentId: z.string().optional().describe("Agent identifier - auto-detected if not provided"),
-  timeout: z.number().positive({ message: "Timeout must be positive" }).default(3e4),
-  logLevel: z.enum(["debug", "info", "warn", "error"]).default("info")
-});
-function loadConfig() {
-  try {
-    const config = configSchema.parse({
-      apiKey: process.env.MEMORYRELAY_API_KEY,
-      apiUrl: process.env.MEMORYRELAY_API_URL,
-      agentId: process.env.MEMORYRELAY_AGENT_ID,
-      timeout: process.env.MEMORYRELAY_TIMEOUT ? parseInt(process.env.MEMORYRELAY_TIMEOUT, 10) : void 0,
-      logLevel: process.env.MEMORYRELAY_LOG_LEVEL
-    });
-    return config;
-  } catch (error) {
-    if (error instanceof z.ZodError) {
-      const issues = error.issues.map(
-        (issue) => `  - ${issue.path.join(".")}: ${issue.message}`
-      ).join("\n");
-      throw new Error(
-        `Configuration validation failed:
-${issues}
-
-Please check your environment variables:
-  - MEMORYRELAY_API_KEY (required, starts with "mem_")
-  - MEMORYRELAY_API_URL (optional, default: https://api.memoryrelay.net)
-  - MEMORYRELAY_AGENT_ID (optional, auto-detected)
-  - MEMORYRELAY_TIMEOUT (optional, default: 30000)
-  - MEMORYRELAY_LOG_LEVEL (optional, default: info)`
-      );
-    }
-    throw error;
-  }
-}
-function getAgentId(config) {
-  if (config.agentId) {
-    return config.agentId;
-  }
-  if (process.env.OPENCLAW_AGENT_NAME) {
-    return process.env.OPENCLAW_AGENT_NAME;
-  }
-  const hostname = process.env.HOSTNAME || "unknown";
-  return `agent-${hostname.slice(0, 8)}`;
-}
-
-// src/logger.ts
-var LOG_LEVELS = {
-  debug: 0,
-  info: 1,
-  warn: 2,
-  error: 3
-};
-var Logger = class {
-  minLevel;
-  constructor(level = "info") {
-    this.minLevel = LOG_LEVELS[level];
-  }
-  /**
-   * Mask sensitive data in log messages
-   * - API keys starting with "mem_" are masked
-   * - Internal paths are sanitized
-   */
-  sanitize(message) {
-    let sanitized = message;
-    sanitized = sanitized.replace(/mem_[a-zA-Z0-9_-]+/g, "mem_****");
-    sanitized = sanitized.replace(/\/[a-zA-Z0-9_\-./]+\.(ts|js|json)/g, "<file>");
-    sanitized = sanitized.replace(/at\s+[^\s]+\s+\([^)]+\)/g, "at <location>");
-    return sanitized;
-  }
-  /**
-   * Format log message with timestamp and level
-   */
-  format(level, message, data) {
-    const timestamp = (/* @__PURE__ */ new Date()).toISOString();
-    const sanitizedMessage = this.sanitize(message);
-    let output = `[${timestamp}] [${level.toUpperCase()}] ${sanitizedMessage}`;
-    if (data !== void 0) {
-      const sanitizedData = this.sanitize(JSON.stringify(data, null, 2));
-      output += `
-${sanitizedData}`;
-    }
-    return output;
-  }
-  debug(message, data) {
-    if (this.minLevel <= LOG_LEVELS.debug) {
-      console.error(this.format("debug", message, data));
-    }
-  }
-  info(message, data) {
-    if (this.minLevel <= LOG_LEVELS.info) {
-      console.error(this.format("info", message, data));
-    }
-  }
-  warn(message, data) {
-    if (this.minLevel <= LOG_LEVELS.warn) {
-      console.error(this.format("warn", message, data));
-    }
-  }
-  error(message, data) {
-    if (this.minLevel <= LOG_LEVELS.error) {
-      console.error(this.format("error", message, data));
-    }
-  }
-};
-var logger;
-function initLogger(level = "info") {
-  logger = new Logger(level);
-  return logger;
-}
-function getLogger() {
-  if (!logger) {
-    logger = new Logger();
-  }
-  return logger;
-}
+import {
+  MemoryRelayClient,
+  getAgentId,
+  getEnabledTools,
+  getLogger,
+  initLogger,
+  loadConfig
+} from "./chunk-P6TZEH6O.js";
 
 // src/server.ts
 import { Server } from "@modelcontextprotocol/sdk/server/index.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import {
   CallToolRequestSchema,
-  ListToolsRequestSchema,
-  ListResourcesRequestSchema,
-  ListResourceTemplatesRequestSchema,
-  ReadResourceRequestSchema,
-  ListPromptsRequestSchema,
-  GetPromptRequestSchema
+  ListToolsRequestSchema
 } from "@modelcontextprotocol/sdk/types.js";
-import { z as z2 } from "zod";
-
-// src/client.ts
-var MAX_RETRIES = 3;
-var INITIAL_DELAY_MS = 1e3;
-var MAX_CONTENT_SIZE = 50 * 1024;
-async function withRetry(fn, retries = MAX_RETRIES) {
-  let lastError;
-  for (let attempt = 0; attempt <= retries; attempt++) {
-    try {
-      return await fn();
-    } catch (error) {
-      lastError = error instanceof Error ? error : new Error(String(error));
-      if (lastError.message.includes("401") || lastError.message.includes("403") || lastError.message.includes("404") || lastError.message.includes("400")) {
-        throw lastError;
-      }
-      if (attempt === retries) {
-        throw lastError;
-      }
-      const delay = INITIAL_DELAY_MS * Math.pow(2, attempt);
-      const jitter = Math.random() * 0.3 * delay;
-      await new Promise((resolve) => setTimeout(resolve, delay + jitter));
-    }
-  }
-  throw lastError || new Error("Retry failed");
-}
-function maskApiKey(message, apiKey) {
-  if (!apiKey) return message;
-  const maskedKey = apiKey.substring(0, 8) + "***";
-  return message.replace(new RegExp(apiKey, "g"), maskedKey);
-}
-var MemoryRelayClient = class {
-  config;
-  logger = getLogger();
-  constructor(config) {
-    this.config = config;
-    this.logger.info("MemoryRelay client initialized", {
-      apiUrl: config.apiUrl,
-      agentId: config.agentId
-    });
-  }
-  /**
-   * Make authenticated HTTP request to MemoryRelay API with retry logic
-   */
-  async request(method, path, body) {
-    return withRetry(async () => {
-      const url = `${this.config.apiUrl}${path}`;
-      this.logger.debug(`API request: ${method} ${path}`);
-      const controller = new AbortController();
-      const timeout = setTimeout(() => controller.abort(), this.config.timeout);
-      try {
-        const response = await fetch(url, {
-          method,
-          headers: {
-            "Content-Type": "application/json",
-            "Authorization": `Bearer ${this.config.apiKey}`,
-            "User-Agent": "@memoryrelay/mcp-server"
-          },
-          body: body ? JSON.stringify(body) : void 0,
-          signal: controller.signal
-        });
-        if (!response.ok) {
-          if (response.status === 429) {
-            const retryAfter = response.headers.get("Retry-After");
-            const waitMs = retryAfter ? parseInt(retryAfter) * 1e3 : 5e3;
-            this.logger.warn(`Rate limited, waiting ${waitMs}ms`);
-            await new Promise((resolve) => setTimeout(resolve, waitMs));
-            throw new Error(`Rate limited: 429 - Retry after ${waitMs}ms`);
-          }
-          const errorData = await response.json().catch(() => ({}));
-          const errorMsg = `API request failed: ${response.status} ${response.statusText}` + (errorData.message ? ` - ${errorData.message}` : "");
-          throw new Error(maskApiKey(errorMsg, this.config.apiKey));
-        }
-        const data = await response.json();
-        this.logger.debug(`API response: ${method} ${path}`, { status: response.status });
-        return data;
-      } catch (error) {
-        if (error instanceof Error) {
-          if (error.name === "AbortError") {
-            throw new Error(`Request timeout after ${this.config.timeout}ms`);
-          }
-          error.message = maskApiKey(error.message, this.config.apiKey);
-        }
-        throw error;
-      } finally {
-        clearTimeout(timeout);
-      }
-    });
-  }
-  /**
-   * Validate content size
-   */
-  validateContentSize(content) {
-    if (content.length > MAX_CONTENT_SIZE) {
-      throw new Error(`Content exceeds maximum size of ${MAX_CONTENT_SIZE} bytes`);
-    }
-  }
-  /**
-   * Store a new memory
-   */
-  async storeMemory(content, metadata) {
-    this.validateContentSize(content);
-    return this.request("POST", "/v1/memories/memories", {
-      content,
-      metadata,
-      agent_id: this.config.agentId
-    });
-  }
-  /**
-   * Search memories using semantic search
-   */
-  async searchMemories(query, limit = 10, threshold = 0.5) {
-    this.validateContentSize(query);
-    const response = await this.request(
-      "POST",
-      "/v1/memories/memories/search",
-      { query, limit, threshold, agent_id: this.config.agentId }
-    );
-    return response.data;
-  }
-  /**
-   * List recent memories with pagination
-   */
-  async listMemories(limit = 20, offset = 0) {
-    return this.request(
-      "GET",
-      `/v1/memories/memories?limit=${limit}&offset=${offset}`
-    );
-  }
-  /**
-   * Get a specific memory by ID
-   */
-  async getMemory(id) {
-    return this.request("GET", `/v1/memories/memories/${id}`);
-  }
-  /**
-   * Update an existing memory
-   */
-  async updateMemory(id, content, metadata) {
-    this.validateContentSize(content);
-    return this.request("PATCH", `/v1/memories/memories/${id}`, {
-      content,
-      metadata
-    });
-  }
-  /**
-   * Delete a memory
-   */
-  async deleteMemory(id) {
-    await this.request("DELETE", `/v1/memories/memories/${id}`);
-  }
-  /**
-   * Create a named entity
-   */
-  async createEntity(name, type, metadata) {
-    this.validateContentSize(name);
-    return this.request("POST", "/v1/entities", {
-      name,
-      type,
-      metadata
-    });
-  }
-  /**
-   * Link an entity to a memory
-   */
-  async linkEntity(entityId, memoryId, relationship = "mentioned_in") {
-    await this.request("POST", "/v1/entities/links", {
-      entity_id: entityId,
-      memory_id: memoryId,
-      relationship
-    });
-  }
-  /**
-   * Get an entity by ID
-   */
-  async getEntity(id) {
-    return this.request("GET", `/v1/entities/${id}`);
-  }
-  /**
-   * List entities with pagination
-   */
-  async listEntities(limit = 20, offset = 0) {
-    return this.request(
-      "GET",
-      `/v1/entities?limit=${limit}&offset=${offset}`
-    );
-  }
-  /**
-   * Delete an entity
-   */
-  async deleteEntity(id) {
-    await this.request("DELETE", `/v1/entities/${id}`);
-  }
-  /**
-   * Health check - verify API connectivity
-   */
-  async healthCheck() {
-    try {
-      await this.request("GET", "/v1/health");
-      return {
-        status: "healthy",
-        message: "API connection successful"
-      };
-    } catch (error) {
-      const errorMsg = error instanceof Error ? error.message : "Unknown error";
-      return {
-        status: "unhealthy",
-        message: `API connection failed: ${errorMsg}`
-      };
-    }
-  }
-};
-
-// src/server.ts
+import { z } from "zod";
 function sanitizeHtml(str) {
   return str.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;").replace(/'/g, "&#x27;").replace(/\//g, "&#x2F;");
 }
-var uuidSchema = z2.string().uuid();
+var uuidSchema = z.string().uuid();
 function validateUuid(id, fieldName = "id") {
   const result = uuidSchema.safeParse(id);
   if (!result.success) {
@@ -361,35 +30,50 @@ var MemoryRelayMCPServer = class {
   server;
   client;
   logger = getLogger();
-  constructor(config) {
-    this.client = new MemoryRelayClient(config);
+  activeSessionId = null;
+  enabledTools = null;
+  constructor(config, client) {
+    this.client = client ?? new MemoryRelayClient(config);
+    this.enabledTools = getEnabledTools();
     this.server = new Server(
       {
         name: "@memoryrelay/mcp-server",
-        version: "0.1.9"
+        version: "0.3.0"
       },
       {
         capabilities: {
-          tools: {},
-          resources: {},
-          prompts: {}
-        }
+          tools: {}
+        },
+        instructions: [
+          "Recommended workflow:",
+          "1. Call project_context(project) to load hot-tier memories for context",
+          "2. Call session_start(project, goal) to begin tracking your work",
+          "3. Call decision_check(project, topic) before making architectural choices",
+          "4. Call pattern_search(query) to find established conventions",
+          "5. Work on the task, using memory_store for important findings",
+          "6. Call session_end(session_id, summary) when done"
+        ].join("\n")
       }
     );
-    this.setupToolHandlers();
-    this.setupResourceHandlers();
-    this.setupPromptHandlers();
+    this.setupHandlers();
     this.logger.info("MCP server initialized");
   }
   /**
-   * Setup MCP tool handlers
+   * Check if a tool is enabled by the current tool group configuration.
+   */
+  isToolEnabled(name) {
+    return this.enabledTools === null || this.enabledTools.has(name);
+  }
+  /**
+   * Setup MCP protocol handlers
    */
-  setupToolHandlers() {
-    this.server.setRequestHandler(ListToolsRequestSchema, async () => ({
-      tools: [
+  setupHandlers() {
+    this.server.setRequestHandler(ListToolsRequestSchema, async () => {
+      const sessionHint = this.activeSessionId ? ` Active session: ${this.activeSessionId}.` : " Tip: Call session_start first to track what you are working on.";
+      const allTools = [
         {
           name: "memory_store",
-          description: "Store a new memory. Use this to save important information, facts, preferences, or context that should be remembered for future conversations.",
+          description: `Store a new memory. Use this to save important information, facts, preferences, or context that should be remembered for future conversations.${sessionHint}`,
           inputSchema: {
             type: "object",
             properties: {
@@ -401,6 +85,35 @@ var MemoryRelayMCPServer = class {
                 type: "object",
                 description: "Optional key-value metadata to attach to the memory",
                 additionalProperties: { type: "string" }
+              },
+              deduplicate: {
+                type: "boolean",
+                description: "Check for duplicate/near-duplicate content before storing. Returns existing memory if match found.",
+                default: false
+              },
+              dedup_threshold: {
+                type: "number",
+                description: "Semantic similarity threshold for dedup (0.5-1.0). Only used when deduplicate=true.",
+                minimum: 0.5,
+                maximum: 1,
+                default: 0.95
+              },
+              project: {
+                type: "string",
+                description: 'Project slug to associate the memory with (e.g., "my-api")',
+                maxLength: 100
+              },
+              importance: {
+                type: "number",
+                description: "Memory importance (0.0-1.0). Defaults to 0.5. Values >= 0.8 promote to hot tier.",
+                minimum: 0,
+                maximum: 1,
+                default: 0.5
+              },
+              tier: {
+                type: "string",
+                description: 'Memory tier override: "hot" (always in context), "warm" (default), "cold" (archived). Auto-computed from importance if omitted.',
+                enum: ["hot", "warm", "cold"]
               }
             },
             required: ["content"]
@@ -408,7 +121,7 @@ var MemoryRelayMCPServer = class {
         },
         {
           name: "memory_search",
-          description: "Search memories using natural language. Returns the most relevant memories based on semantic similarity to the query.",
+          description: "Search memories using natural language. Returns the most relevant memories based on semantic similarity to the query. Omit agent_id to search across all agents.",
           inputSchema: {
             type: "object",
             properties: {
@@ -416,6 +129,10 @@ var MemoryRelayMCPServer = class {
                 type: "string",
                 description: "Natural language search query"
               },
+              agent_id: {
+                type: "string",
+                description: "Optional agent ID to scope the search. If omitted, searches across all agents."
+              },
               limit: {
                 type: "number",
                 description: "Maximum number of results to return (1-50)",
@@ -429,6 +146,41 @@ var MemoryRelayMCPServer = class {
                 minimum: 0,
                 maximum: 1,
                 default: 0.5
+              },
+              include_confidential: {
+                type: "boolean",
+                description: "Include confidential memories in results (default: false)",
+                default: false
+              },
+              include_archived: {
+                type: "boolean",
+                description: "Include archived memories in results (default: false)",
+                default: false
+              },
+              compress: {
+                type: "boolean",
+                description: "Enable context compression on results",
+                default: false
+              },
+              max_context_tokens: {
+                type: "number",
+                description: "Target total token budget for compressed results"
+              },
+              project: {
+                type: "string",
+                description: "Filter by project slug. Omit for cross-project search.",
+                maxLength: 100
+              },
+              tier: {
+                type: "string",
+                description: 'Filter by tier: "hot", "warm", or "cold". Omit to search all tiers.',
+                enum: ["hot", "warm", "cold"]
+              },
+              min_importance: {
+                type: "number",
+                description: "Minimum importance threshold (0.0-1.0). Only return memories above this.",
+                minimum: 0,
+                maximum: 1
               }
             },
             required: ["query"]
@@ -557,79 +309,803 @@ var MemoryRelayMCPServer = class {
           }
         },
         {
-          name: "memory_health",
-          description: "Check API connectivity and health status.",
+          name: "entity_list",
+          description: "List entities in the knowledge graph with pagination. Entities are people, places, organizations, projects, and concepts extracted from memories.",
           inputSchema: {
             type: "object",
-            properties: {}
+            properties: {
+              limit: {
+                type: "number",
+                description: "Number of entities to return (1-100)",
+                minimum: 1,
+                maximum: 100,
+                default: 20
+              },
+              offset: {
+                type: "number",
+                description: "Offset for pagination",
+                minimum: 0,
+                default: 0
+              }
+            }
           }
-        }
-      ]
-    }));
-    this.server.setRequestHandler(CallToolRequestSchema, async (request) => {
-      const { name, arguments: args = {} } = request.params;
-      this.logger.debug(`Tool called: ${name}`, args);
-      try {
-        switch (name) {
-          case "memory_store": {
-            const memory = await this.client.storeMemory(
-              args.content,
-              args.metadata
-            );
-            return {
-              content: [
-                {
-                  type: "text",
-                  text: JSON.stringify(memory, null, 2)
-                }
-              ]
-            };
+        },
+        {
+          name: "agent_list",
+          description: "List all agents with their memory counts. Agents are namespaces that isolate memories.",
+          inputSchema: {
+            type: "object",
+            properties: {
+              limit: {
+                type: "number",
+                description: "Number of agents to return (1-100)",
+                minimum: 1,
+                maximum: 100,
+                default: 20
+              }
+            }
           }
-          case "memory_search": {
-            const results = await this.client.searchMemories(
-              args.query,
-              args.limit,
-              args.threshold
-            );
-            return {
-              content: [
-                {
-                  type: "text",
-                  text: JSON.stringify(
-                    { memories: results, total: results.length },
-                    null,
-                    2
-                  )
-                }
-              ]
-            };
+        },
+        {
+          name: "agent_create",
+          description: "Create a named agent. Agents are namespaces that isolate memories for different use cases or AI assistants.",
+          inputSchema: {
+            type: "object",
+            properties: {
+              name: {
+                type: "string",
+                description: 'Agent name (descriptive, e.g. "iris", "friday", "code-assistant")'
+              },
+              description: {
+                type: "string",
+                description: "Optional description of the agent's purpose"
+              }
+            },
+            required: ["name"]
           }
-          case "memory_list": {
-            const response = await this.client.listMemories(
-              args.limit,
-              args.offset
-            );
-            return {
-              content: [
-                {
-                  type: "text",
-                  text: JSON.stringify(response, null, 2)
-                }
-              ]
-            };
+        },
+        {
+          name: "agent_get",
+          description: "Get details of a specific agent by ID, including memory count.",
+          inputSchema: {
+            type: "object",
+            properties: {
+              id: {
+                type: "string",
+                description: "The agent ID (UUID) to retrieve"
+              }
+            },
+            required: ["id"]
           }
-          case "memory_get": {
-            const id = args.id;
-            validateUuid(id, "memory_id");
-            const memory = await this.client.getMemory(id);
-            return {
-              content: [
-                {
-                  type: "text",
-                  text: JSON.stringify(memory, null, 2)
-                }
-              ]
-            };
+        },
+        {
+          name: "entity_graph",
+          description: "Explore the knowledge graph around an entity. Returns neighboring entities and their relationships up to N hops away. Useful for understanding connections between people, projects, and concepts.",
+          inputSchema: {
+            type: "object",
+            properties: {
+              entity_id: {
+                type: "string",
+                description: "Entity UUID to explore from"
+              },
+              depth: {
+                type: "number",
+                description: "How many hops to traverse (1 or 2)",
+                minimum: 1,
+                maximum: 2,
+                default: 1
+              },
+              max_neighbors: {
+                type: "number",
+                description: "Maximum neighbor entities to return (1-100)",
+                minimum: 1,
+                maximum: 100,
+                default: 50
+              }
+            },
+            required: ["entity_id"]
+          }
+        },
+        {
+          name: "memory_batch_store",
+          description: "Store multiple memories in a single operation. More efficient than calling memory_store repeatedly when saving several related facts or observations.",
+          inputSchema: {
+            type: "object",
+            properties: {
+              memories: {
+                type: "array",
+                description: "Array of memories to store (1-100 items)",
+                items: {
+                  type: "object",
+                  properties: {
+                    content: {
+                      type: "string",
+                      description: "The memory content to store"
+                    },
+                    metadata: {
+                      type: "object",
+                      description: "Optional key-value metadata",
+                      additionalProperties: { type: "string" }
+                    }
+                  },
+                  required: ["content"]
+                },
+                minItems: 1,
+                maxItems: 100
+              }
+            },
+            required: ["memories"]
+          }
+        },
+        {
+          name: "memory_context",
+          description: "Build a formatted context string from relevant memories for a given query. Returns ranked memories with similarity scores, ready for use in prompts. More convenient than memory_search when you need a single context block.",
+          inputSchema: {
+            type: "object",
+            properties: {
+              query: {
+                type: "string",
+                description: "Natural language query to find relevant memories"
+              },
+              limit: {
+                type: "number",
+                description: "Maximum number of memories to include (1-50)",
+                minimum: 1,
+                maximum: 50,
+                default: 10
+              },
+              threshold: {
+                type: "number",
+                description: "Minimum similarity threshold (0-1)",
+                minimum: 0,
+                maximum: 1,
+                default: 0.5
+              },
+              max_tokens: {
+                type: "number",
+                description: "Maximum token budget for the context string. Results are truncated to fit."
+              }
+            },
+            required: ["query"]
+          }
+        },
+        {
+          name: "project_register",
+          description: "Register a project (codebase/repository) to scope memories, sessions, and decisions. Projects have a unique slug for ergonomic referencing.",
+          inputSchema: {
+            type: "object",
+            properties: {
+              slug: {
+                type: "string",
+                description: 'URL-safe identifier (lowercase, hyphens allowed, e.g., "my-api")',
+                pattern: "^[a-z0-9][a-z0-9-]*$",
+                maxLength: 100
+              },
+              name: {
+                type: "string",
+                description: 'Human-readable project name (e.g., "My API Service")',
+                maxLength: 255
+              },
+              description: {
+                type: "string",
+                description: "Optional project description"
+              },
+              stack: {
+                type: "object",
+                description: 'Technical stack metadata (e.g., {"languages": ["python"], "frameworks": ["fastapi"]})'
+              },
+              repo_url: {
+                type: "string",
+                description: 'Repository URL (e.g., "https://github.com/org/repo")',
+                maxLength: 500
+              }
+            },
+            required: ["slug", "name"]
+          }
+        },
+        {
+          name: "project_list",
+          description: "List registered projects. Shows all projects with their memory counts.",
+          inputSchema: {
+            type: "object",
+            properties: {
+              limit: {
+                type: "number",
+                description: "Maximum number of projects to return (1-100)",
+                minimum: 1,
+                maximum: 100,
+                default: 20
+              }
+            }
+          }
+        },
+        {
+          name: "project_info",
+          description: "Get detailed information about a specific project by its slug, including memory count and stack metadata.",
+          inputSchema: {
+            type: "object",
+            properties: {
+              slug: {
+                type: "string",
+                description: "Project slug to look up"
+              }
+            },
+            required: ["slug"]
+          }
+        },
+        // ── Project Relationship Tools (Issue #186) ──
+        {
+          name: "project_add_relationship",
+          description: "Register a relationship between two projects (e.g., depends_on, api_consumer, shares_schema, shares_infra, pattern_source, forked_from).",
+          inputSchema: {
+            type: "object",
+            properties: {
+              from: {
+                type: "string",
+                description: "Source project slug"
+              },
+              to: {
+                type: "string",
+                description: "Target project slug"
+              },
+              type: {
+                type: "string",
+                description: "Relationship type (e.g., depends_on, api_consumer, shares_schema)"
+              },
+              details: {
+                type: "object",
+                description: "Optional relationship metadata",
+                additionalProperties: true
+              }
+            },
+            required: ["from", "to", "type"]
+          }
+        },
+        {
+          name: "project_dependencies",
+          description: "What does this project depend on? Returns outgoing depends_on and api_consumer relationships.",
+          inputSchema: {
+            type: "object",
+            properties: {
+              project: {
+                type: "string",
+                description: "Project slug"
+              }
+            },
+            required: ["project"]
+          }
+        },
+        {
+          name: "project_dependents",
+          description: "What depends on this project? Returns incoming depends_on and api_consumer relationships.",
+          inputSchema: {
+            type: "object",
+            properties: {
+              project: {
+                type: "string",
+                description: "Project slug"
+              }
+            },
+            required: ["project"]
+          }
+        },
+        {
+          name: "project_related",
+          description: "All related projects with relationship types and direction indicators.",
+          inputSchema: {
+            type: "object",
+            properties: {
+              project: {
+                type: "string",
+                description: "Project slug"
+              }
+            },
+            required: ["project"]
+          }
+        },
+        {
+          name: "project_impact",
+          description: "Impact analysis: given a change description, which dependent projects might be affected? Searches decisions and memories in downstream projects.",
+          inputSchema: {
+            type: "object",
+            properties: {
+              project: {
+                type: "string",
+                description: "Project slug being changed"
+              },
+              change_description: {
+                type: "string",
+                description: "Description of the change to analyze (max 5000 chars)",
+                maxLength: 5e3
+              }
+            },
+            required: ["project", "change_description"]
+          }
+        },
+        {
+          name: "project_shared_patterns",
+          description: "What do two projects have in common? Returns patterns adopted by both projects.",
+          inputSchema: {
+            type: "object",
+            properties: {
+              project_a: {
+                type: "string",
+                description: "First project slug"
+              },
+              project_b: {
+                type: "string",
+                description: "Second project slug"
+              }
+            },
+            required: ["project_a", "project_b"]
+          }
+        },
+        {
+          name: "memory_health",
+          description: "Check API connectivity and health status.",
+          inputSchema: {
+            type: "object",
+            properties: {}
+          }
+        },
+        {
+          name: "session_start",
+          description: "Start a new session to group related memories. Sessions track bounded interaction periods (e.g., a coding session, a conversation). Use session_recall to see what happened in previous sessions.",
+          inputSchema: {
+            type: "object",
+            properties: {
+              title: {
+                type: "string",
+                description: 'Session title or goal (e.g., "Fix email queue retry logic")',
+                maxLength: 500
+              },
+              project: {
+                type: "string",
+                description: 'Project label for filtering sessions (e.g., "northrelay")',
+                maxLength: 255
+              },
+              metadata: {
+                type: "object",
+                description: "Optional metadata",
+                additionalProperties: { type: "string" }
+              }
+            }
+          }
+        },
+        {
+          name: "session_end",
+          description: "End an active session with an optional summary of what was accomplished.",
+          inputSchema: {
+            type: "object",
+            properties: {
+              id: {
+                type: "string",
+                description: "Session ID (UUID) to end"
+              },
+              summary: {
+                type: "string",
+                description: "Summary of what was accomplished during the session",
+                maxLength: 5e4
+              }
+            },
+            required: ["id"]
+          }
+        },
+        {
+          name: "session_recall",
+          description: "Recall a session by ID, including all memories created during it. Use this to review what happened in a past session.",
+          inputSchema: {
+            type: "object",
+            properties: {
+              id: {
+                type: "string",
+                description: "Session ID (UUID) to recall"
+              }
+            },
+            required: ["id"]
+          }
+        },
+        {
+          name: "session_list",
+          description: "List recent sessions, optionally filtered by project or status. Shows session summaries to understand what happened in previous sessions.",
+          inputSchema: {
+            type: "object",
+            properties: {
+              limit: {
+                type: "number",
+                description: "Maximum number of sessions to return (1-100)",
+                minimum: 1,
+                maximum: 100,
+                default: 20
+              },
+              project: {
+                type: "string",
+                description: "Filter by project label"
+              },
+              status: {
+                type: "string",
+                enum: ["active", "ended"],
+                description: "Filter by session status"
+              }
+            }
+          }
+        },
+        {
+          name: "decision_record",
+          description: "Record an architectural decision with rationale. Use to log important technical choices, design decisions, or policy changes so they can be referenced later.",
+          inputSchema: {
+            type: "object",
+            properties: {
+              title: {
+                type: "string",
+                description: 'Decision title (e.g., "Use PostgreSQL instead of MongoDB")',
+                maxLength: 500
+              },
+              rationale: {
+                type: "string",
+                description: "Why this decision was made. Include context, constraints, and reasoning.",
+                maxLength: 5e4
+              },
+              alternatives: {
+                type: "string",
+                description: "Alternatives that were considered and why they were rejected"
+              },
+              project: {
+                type: "string",
+                description: "Project slug to scope the decision to",
+                maxLength: 100
+              },
+              tags: {
+                type: "array",
+                items: { type: "string" },
+                description: 'Tags for categorization (e.g., ["architecture", "database"])'
+              },
+              status: {
+                type: "string",
+                enum: ["active", "experimental"],
+                description: "Decision status (default: active)"
+              }
+            },
+            required: ["title", "rationale"]
+          }
+        },
+        {
+          name: "decision_list",
+          description: "List recorded decisions, optionally filtered by project, status, or tags.",
+          inputSchema: {
+            type: "object",
+            properties: {
+              limit: {
+                type: "number",
+                description: "Maximum results (1-100, default 20)",
+                minimum: 1,
+                maximum: 100,
+                default: 20
+              },
+              project: {
+                type: "string",
+                description: "Filter by project slug"
+              },
+              status: {
+                type: "string",
+                enum: ["active", "superseded", "reverted", "experimental"],
+                description: "Filter by decision status"
+              },
+              tags: {
+                type: "string",
+                description: "Comma-separated tags to filter by"
+              }
+            }
+          }
+        },
+        {
+          name: "decision_supersede",
+          description: "Supersede an existing decision with a new one. Marks the old decision as superseded and creates a new active decision.",
+          inputSchema: {
+            type: "object",
+            properties: {
+              id: {
+                type: "string",
+                description: "ID (UUID) of the decision to supersede"
+              },
+              title: {
+                type: "string",
+                description: "Title of the new decision"
+              },
+              rationale: {
+                type: "string",
+                description: "Rationale for the new decision"
+              },
+              alternatives: {
+                type: "string",
+                description: "Alternatives considered"
+              },
+              tags: {
+                type: "array",
+                items: { type: "string" },
+                description: "Tags for the new decision (inherits from old if omitted)"
+              }
+            },
+            required: ["id", "title", "rationale"]
+          }
+        },
+        {
+          name: "decision_check",
+          description: "Check if there are existing decisions about a topic using semantic search. Use this before making a new decision to see if the topic has already been addressed.",
+          inputSchema: {
+            type: "object",
+            properties: {
+              query: {
+                type: "string",
+                description: "Natural language query describing the decision topic to check"
+              },
+              project: {
+                type: "string",
+                description: "Filter by project slug"
+              },
+              limit: {
+                type: "number",
+                description: "Maximum results (1-20, default 5)",
+                minimum: 1,
+                maximum: 20,
+                default: 5
+              },
+              threshold: {
+                type: "number",
+                description: "Minimum similarity threshold (0-1, default 0.3)",
+                minimum: 0,
+                maximum: 1,
+                default: 0.3
+              },
+              include_superseded: {
+                type: "boolean",
+                description: "Include superseded decisions in results (default: false)",
+                default: false
+              }
+            },
+            required: ["query"]
+          }
+        },
+        {
+          name: "pattern_create",
+          description: 'Create a reusable development pattern or convention. Use to document patterns like "always use Zod for validation" or "error responses follow RFC 7807" so they can be discovered and adopted across projects.',
+          inputSchema: {
+            type: "object",
+            properties: {
+              title: {
+                type: "string",
+                description: 'Pattern title (e.g., "Zod validation at API boundaries")',
+                maxLength: 500
+              },
+              description: {
+                type: "string",
+                description: "Full description with context, rationale, and when to apply this pattern",
+                maxLength: 5e4
+              },
+              category: {
+                type: "string",
+                description: 'Category (e.g., "validation", "error-handling", "auth", "testing")',
+                maxLength: 100
+              },
+              example_code: {
+                type: "string",
+                description: "Code snippet demonstrating the pattern"
+              },
+              scope: {
+                type: "string",
+                enum: ["global", "project"],
+                description: "Scope: global (all projects) or project (specific projects). Default: global"
+              },
+              tags: {
+                type: "array",
+                items: { type: "string" },
+                description: "Tags for categorization"
+              },
+              source_project: {
+                type: "string",
+                description: "Slug of the project where this pattern was first established"
+              }
+            },
+            required: ["title", "description"]
+          }
+        },
+        {
+          name: "pattern_search",
+          description: "Search for development patterns using semantic similarity. When working on a project, shows both global patterns and patterns adopted by that project.",
+          inputSchema: {
+            type: "object",
+            properties: {
+              query: {
+                type: "string",
+                description: 'Natural language query describing the pattern to find (e.g., "validation", "error handling")'
+              },
+              category: {
+                type: "string",
+                description: "Filter by category"
+              },
+              project: {
+                type: "string",
+                description: "Project context \u2014 shows global patterns plus patterns adopted by this project"
+              },
+              limit: {
+                type: "number",
+                description: "Maximum results (1-50, default 10)",
+                minimum: 1,
+                maximum: 50,
+                default: 10
+              },
+              threshold: {
+                type: "number",
+                description: "Minimum similarity threshold (0-1, default 0.3)",
+                minimum: 0,
+                maximum: 1,
+                default: 0.3
+              }
+            },
+            required: ["query"]
+          }
+        },
+        {
+          name: "pattern_adopt",
+          description: "Mark a pattern as adopted by a project. This links the pattern to the project so it shows up in project-scoped searches.",
+          inputSchema: {
+            type: "object",
+            properties: {
+              id: {
+                type: "string",
+                description: "Pattern ID (UUID) to adopt"
+              },
+              project: {
+                type: "string",
+                description: "Project slug to adopt this pattern for"
+              }
+            },
+            required: ["id", "project"]
+          }
+        },
+        {
+          name: "pattern_suggest",
+          description: "Suggest relevant patterns for a project based on what similar projects have adopted. Returns patterns not yet adopted by the target project, ranked by popularity.",
+          inputSchema: {
+            type: "object",
+            properties: {
+              project: {
+                type: "string",
+                description: "Project slug to get suggestions for"
+              },
+              limit: {
+                type: "number",
+                description: "Maximum suggestions (1-50, default 10)",
+                minimum: 1,
+                maximum: 50,
+                default: 10
+              }
+            },
+            required: ["project"]
+          }
+        },
+        {
+          name: "project_context",
+          description: "Get full project context for LLM consumption. Returns hot-tier memories, active decisions, adopted patterns, and a pre-formatted markdown context string.",
+          inputSchema: {
+            type: "object",
+            properties: {
+              project: {
+                type: "string",
+                description: "Project slug to get context for"
+              }
+            },
+            required: ["project"]
+          }
+        },
+        {
+          name: "memory_promote",
+          description: "Update a memory's importance and tier. Use to promote critical memories to hot tier (always in context) or demote them to cold tier (archived).",
+          inputSchema: {
+            type: "object",
+            properties: {
+              memory_id: {
+                type: "string",
+                description: "Memory ID (UUID) to promote/demote"
+              },
+              importance: {
+                type: "number",
+                description: "New importance value (0.0-1.0). Values >= 0.8 promote to hot tier.",
+                minimum: 0,
+                maximum: 1
+              },
+              tier: {
+                type: "string",
+                description: 'Optional tier override: "hot", "warm", or "cold". Auto-computed from importance if omitted.',
+                enum: ["hot", "warm", "cold"]
+              }
+            },
+            required: ["memory_id", "importance"]
+          }
+        }
+      ];
+      return {
+        tools: allTools.filter((t) => this.isToolEnabled(t.name))
+      };
+    });
+    this.server.setRequestHandler(CallToolRequestSchema, async (request) => {
+      const { name, arguments: args = {} } = request.params;
+      this.logger.debug(`Tool called: ${name}`, args);
+      try {
+        switch (name) {
+          case "memory_store": {
+            const memory = await this.client.storeMemory(
+              args.content,
+              args.metadata,
+              args.deduplicate,
+              args.dedup_threshold,
+              args.project,
+              args.importance,
+              args.tier
+            );
+            return {
+              content: [
+                {
+                  type: "text",
+                  text: JSON.stringify(memory, null, 2)
+                }
+              ]
+            };
+          }
+          case "memory_search": {
+            const searchAgentId = args.agent_id != null ? args.agent_id : null;
+            const results = await this.client.searchMemories(
+              args.query,
+              args.limit,
+              args.threshold,
+              searchAgentId,
+              args.include_confidential ?? false,
+              args.include_archived ?? false,
+              args.compress ?? false,
+              args.max_context_tokens,
+              args.project,
+              args.tier,
+              args.min_importance
+            );
+            return {
+              content: [
+                {
+                  type: "text",
+                  text: JSON.stringify(
+                    { memories: results, total: results.length },
+                    null,
+                    2
+                  )
+                }
+              ]
+            };
+          }
+          case "memory_list": {
+            const response = await this.client.listMemories(
+              args.limit,
+              args.offset
+            );
+            return {
+              content: [
+                {
+                  type: "text",
+                  text: JSON.stringify(response, null, 2)
+                }
+              ]
+            };
+          }
+          case "memory_get": {
+            const id = args.id;
+            validateUuid(id, "memory_id");
+            const memory = await this.client.getMemory(id);
+            return {
+              content: [
+                {
+                  type: "text",
+                  text: JSON.stringify(memory, null, 2)
+                }
+              ]
+            };
           }
           case "memory_update": {
             const id = args.id;
@@ -643,81 +1119,312 @@ var MemoryRelayMCPServer = class {
               content: [
                 {
                   type: "text",
-                  text: JSON.stringify(memory, null, 2)
+                  text: JSON.stringify(memory, null, 2)
+                }
+              ]
+            };
+          }
+          case "memory_delete": {
+            const id = args.id;
+            validateUuid(id, "memory_id");
+            await this.client.deleteMemory(id);
+            return {
+              content: [
+                {
+                  type: "text",
+                  text: JSON.stringify(
+                    { success: true, message: "Memory deleted successfully" },
+                    null,
+                    2
+                  )
+                }
+              ]
+            };
+          }
+          case "entity_create": {
+            const entitySchema = z.object({
+              name: z.string().min(1).max(200),
+              type: z.enum(["person", "place", "organization", "project", "concept", "other"]),
+              metadata: z.record(z.string()).optional()
+            });
+            const validatedInput = entitySchema.parse(args);
+            const sanitizedName = sanitizeHtml(validatedInput.name);
+            const entity = await this.client.createEntity(
+              sanitizedName,
+              validatedInput.type,
+              validatedInput.metadata
+            );
+            return {
+              content: [
+                {
+                  type: "text",
+                  text: JSON.stringify(entity, null, 2)
+                }
+              ]
+            };
+          }
+          case "entity_link": {
+            const linkSchema = z.object({
+              entity_id: z.string().uuid(),
+              memory_id: z.string().uuid(),
+              relationship: z.string().default("mentioned_in")
+            });
+            const validatedInput = linkSchema.parse(args);
+            await this.client.linkEntity(
+              validatedInput.entity_id,
+              validatedInput.memory_id,
+              validatedInput.relationship
+            );
+            return {
+              content: [
+                {
+                  type: "text",
+                  text: JSON.stringify(
+                    {
+                      success: true,
+                      message: "Entity linked to memory successfully",
+                      entity_id: validatedInput.entity_id,
+                      memory_id: validatedInput.memory_id,
+                      relationship: validatedInput.relationship
+                    },
+                    null,
+                    2
+                  )
+                }
+              ]
+            };
+          }
+          case "entity_list": {
+            const response = await this.client.listEntities(
+              args.limit,
+              args.offset
+            );
+            return {
+              content: [
+                {
+                  type: "text",
+                  text: JSON.stringify(response, null, 2)
                 }
               ]
             };
           }
-          case "memory_delete": {
-            const id = args.id;
-            validateUuid(id, "memory_id");
-            await this.client.deleteMemory(id);
+          case "agent_list": {
+            const response = await this.client.listAgents(
+              args.limit
+            );
             return {
               content: [
                 {
                   type: "text",
-                  text: JSON.stringify(
-                    { success: true, message: "Memory deleted successfully" },
-                    null,
-                    2
-                  )
+                  text: JSON.stringify(response, null, 2)
                 }
               ]
             };
           }
-          case "entity_create": {
-            const entitySchema = z2.object({
-              name: z2.string().min(1).max(200),
-              type: z2.enum(["person", "place", "organization", "project", "concept", "other"]),
-              metadata: z2.record(z2.string()).optional()
+          case "agent_create": {
+            const createSchema = z.object({
+              name: z.string().min(1).max(255),
+              description: z.string().max(1e3).optional()
             });
-            const validatedInput = entitySchema.parse(args);
+            const validatedInput = createSchema.parse(args);
             const sanitizedName = sanitizeHtml(validatedInput.name);
-            const entity = await this.client.createEntity(
+            const agent = await this.client.createAgent(
               sanitizedName,
-              validatedInput.type,
-              validatedInput.metadata
+              validatedInput.description
             );
             return {
               content: [
                 {
                   type: "text",
-                  text: JSON.stringify(entity, null, 2)
+                  text: JSON.stringify(agent, null, 2)
                 }
               ]
             };
           }
-          case "entity_link": {
-            const linkSchema = z2.object({
-              entity_id: z2.string().uuid(),
-              memory_id: z2.string().uuid(),
-              relationship: z2.string().default("mentioned_in")
+          case "agent_get": {
+            const id = args.id;
+            validateUuid(id, "agent_id");
+            const agent = await this.client.getAgent(id);
+            return {
+              content: [
+                {
+                  type: "text",
+                  text: JSON.stringify(agent, null, 2)
+                }
+              ]
+            };
+          }
+          case "entity_graph": {
+            const graphSchema = z.object({
+              entity_id: z.string().uuid(),
+              depth: z.number().min(1).max(2).default(1),
+              max_neighbors: z.number().min(1).max(100).default(50)
             });
-            const validatedInput = linkSchema.parse(args);
-            await this.client.linkEntity(
+            const validatedInput = graphSchema.parse(args);
+            const result = await this.client.getEntityNeighborhood(
               validatedInput.entity_id,
-              validatedInput.memory_id,
-              validatedInput.relationship
+              validatedInput.depth,
+              validatedInput.max_neighbors
             );
             return {
               content: [
                 {
                   type: "text",
-                  text: JSON.stringify(
-                    {
-                      success: true,
-                      message: "Entity linked to memory successfully",
-                      entity_id: validatedInput.entity_id,
-                      memory_id: validatedInput.memory_id,
-                      relationship: validatedInput.relationship
-                    },
-                    null,
-                    2
-                  )
+                  text: JSON.stringify(result, null, 2)
+                }
+              ]
+            };
+          }
+          case "memory_batch_store": {
+            const batchSchema = z.object({
+              memories: z.array(z.object({
+                content: z.string().min(1),
+                metadata: z.record(z.string()).optional()
+              })).min(1).max(100)
+            });
+            const validatedInput = batchSchema.parse(args);
+            const result = await this.client.batchStoreMemories(validatedInput.memories);
+            return {
+              content: [
+                {
+                  type: "text",
+                  text: JSON.stringify(result, null, 2)
+                }
+              ]
+            };
+          }
+          case "memory_context": {
+            const contextSchema = z.object({
+              query: z.string().min(1),
+              limit: z.number().min(1).max(50).default(10),
+              threshold: z.number().min(0).max(1).default(0.5),
+              max_tokens: z.number().positive().optional()
+            });
+            const validatedInput = contextSchema.parse(args);
+            const result = await this.client.buildContext(
+              validatedInput.query,
+              validatedInput.limit,
+              validatedInput.threshold,
+              validatedInput.max_tokens
+            );
+            return {
+              content: [
+                {
+                  type: "text",
+                  text: JSON.stringify(result, null, 2)
                 }
               ]
             };
           }
+          case "project_register": {
+            const projectSchema = z.object({
+              slug: z.string().min(1).max(100).regex(/^[a-z0-9][a-z0-9-]*$/),
+              name: z.string().min(1).max(255),
+              description: z.string().optional(),
+              stack: z.record(z.unknown()).optional(),
+              repo_url: z.string().max(500).optional()
+            });
+            const validatedInput = projectSchema.parse(args);
+            const project = await this.client.createProject(
+              validatedInput.slug,
+              validatedInput.name,
+              validatedInput.description,
+              validatedInput.stack,
+              validatedInput.repo_url
+            );
+            return {
+              content: [{ type: "text", text: JSON.stringify(project, null, 2) }]
+            };
+          }
+          case "project_list": {
+            const response = await this.client.listProjects(
+              args.limit
+            );
+            return {
+              content: [{ type: "text", text: JSON.stringify(response, null, 2) }]
+            };
+          }
+          case "project_info": {
+            const slug = args.slug;
+            if (!slug) {
+              throw new Error("Project slug is required");
+            }
+            const project = await this.client.getProject(slug);
+            return {
+              content: [{ type: "text", text: JSON.stringify(project, null, 2) }]
+            };
+          }
+          // ── Project Relationship Handlers (Issue #186) ──
+          case "project_add_relationship": {
+            const relSchema = z.object({
+              from: z.string().min(1),
+              to: z.string().min(1),
+              type: z.string().min(1).max(100),
+              details: z.record(z.unknown()).optional()
+            });
+            const relArgs = relSchema.parse(args);
+            const relationship = await this.client.addProjectRelationship(
+              relArgs.from,
+              relArgs.to,
+              relArgs.type,
+              relArgs.details
+            );
+            return {
+              content: [{ type: "text", text: JSON.stringify(relationship, null, 2) }]
+            };
+          }
+          case "project_dependencies": {
+            const depSlug = args.project;
+            if (!depSlug) throw new Error("Project slug is required");
+            const deps = await this.client.getProjectDependencies(depSlug);
+            return {
+              content: [{ type: "text", text: JSON.stringify(deps, null, 2) }]
+            };
+          }
+          case "project_dependents": {
+            const deptSlug = args.project;
+            if (!deptSlug) throw new Error("Project slug is required");
+            const dependents = await this.client.getProjectDependents(deptSlug);
+            return {
+              content: [{ type: "text", text: JSON.stringify(dependents, null, 2) }]
+            };
+          }
+          case "project_related": {
+            const relatedSlug = args.project;
+            if (!relatedSlug) throw new Error("Project slug is required");
+            const related = await this.client.getProjectRelated(relatedSlug);
+            return {
+              content: [{ type: "text", text: JSON.stringify(related, null, 2) }]
+            };
+          }
+          case "project_impact": {
+            const impactSchema = z.object({
+              project: z.string().min(1),
+              change_description: z.string().min(1).max(5e3)
+            });
+            const impactArgs = impactSchema.parse(args);
+            const impact = await this.client.projectImpactAnalysis(
+              impactArgs.project,
+              impactArgs.change_description
+            );
+            return {
+              content: [{ type: "text", text: JSON.stringify(impact, null, 2) }]
+            };
+          }
+          case "project_shared_patterns": {
+            const spSchema = z.object({
+              project_a: z.string().min(1),
+              project_b: z.string().min(1)
+            });
+            const spArgs = spSchema.parse(args);
+            const shared = await this.client.getSharedPatterns(
+              spArgs.project_a,
+              spArgs.project_b
+            );
+            return {
+              content: [{ type: "text", text: JSON.stringify(shared, null, 2) }]
+            };
+          }
           case "memory_health": {
             const health = await this.client.healthCheck();
             return {
@@ -729,13 +1436,203 @@ var MemoryRelayMCPServer = class {
               ]
             };
           }
+          case "session_start": {
+            const session = await this.client.startSession(
+              args.title,
+              args.project,
+              args.metadata
+            );
+            this.activeSessionId = session.id ?? null;
+            return {
+              content: [
+                {
+                  type: "text",
+                  text: JSON.stringify(session, null, 2)
+                }
+              ]
+            };
+          }
+          case "session_end": {
+            const id = args.id;
+            validateUuid(id, "session_id");
+            const session = await this.client.endSession(
+              id,
+              args.summary
+            );
+            if (this.activeSessionId === id) {
+              this.activeSessionId = null;
+            }
+            return {
+              content: [
+                {
+                  type: "text",
+                  text: JSON.stringify(session, null, 2)
+                }
+              ]
+            };
+          }
+          case "session_recall": {
+            const id = args.id;
+            validateUuid(id, "session_id");
+            const session = await this.client.getSession(id);
+            return {
+              content: [
+                {
+                  type: "text",
+                  text: JSON.stringify(session, null, 2)
+                }
+              ]
+            };
+          }
+          case "session_list": {
+            const response = await this.client.listSessions(
+              args.limit,
+              void 0,
+              args.project,
+              args.status
+            );
+            return {
+              content: [
+                {
+                  type: "text",
+                  text: JSON.stringify(response, null, 2)
+                }
+              ]
+            };
+          }
+          case "decision_record": {
+            const decision = await this.client.recordDecision(
+              args.title,
+              args.rationale,
+              args.alternatives,
+              args.project,
+              args.tags,
+              args.status
+            );
+            return {
+              content: [{ type: "text", text: JSON.stringify(decision, null, 2) }]
+            };
+          }
+          case "decision_list": {
+            const response = await this.client.listDecisions(
+              args.limit,
+              args.project,
+              args.status,
+              args.tags
+            );
+            return {
+              content: [{ type: "text", text: JSON.stringify(response, null, 2) }]
+            };
+          }
+          case "decision_supersede": {
+            const id = args.id;
+            validateUuid(id, "decision_id");
+            const decision = await this.client.supersedeDecision(
+              id,
+              args.title,
+              args.rationale,
+              args.alternatives,
+              args.tags
+            );
+            return {
+              content: [{ type: "text", text: JSON.stringify(decision, null, 2) }]
+            };
+          }
+          case "decision_check": {
+            const response = await this.client.checkDecisions(
+              args.query,
+              args.project,
+              args.limit,
+              args.threshold,
+              args.include_superseded ?? false
+            );
+            return {
+              content: [{ type: "text", text: JSON.stringify(response, null, 2) }]
+            };
+          }
+          case "pattern_create": {
+            const patternSchema = z.object({
+              title: z.string().min(1).max(500),
+              description: z.string().min(1).max(5e4),
+              category: z.string().max(100).optional(),
+              example_code: z.string().optional(),
+              scope: z.enum(["global", "project"]).optional(),
+              tags: z.array(z.string()).max(20).optional(),
+              source_project: z.string().max(100).optional()
+            });
+            const validatedInput = patternSchema.parse(args);
+            const pattern = await this.client.createPattern(
+              validatedInput.title,
+              validatedInput.description,
+              validatedInput.category,
+              validatedInput.example_code,
+              validatedInput.scope,
+              validatedInput.tags,
+              validatedInput.source_project
+            );
+            return {
+              content: [{ type: "text", text: JSON.stringify(pattern, null, 2) }]
+            };
+          }
+          case "pattern_search": {
+            const response = await this.client.searchPatterns(
+              args.query,
+              args.category,
+              args.project,
+              args.limit,
+              args.threshold
+            );
+            return {
+              content: [{ type: "text", text: JSON.stringify(response, null, 2) }]
+            };
+          }
+          case "pattern_adopt": {
+            const id = args.id;
+            validateUuid(id, "pattern_id");
+            const pattern = await this.client.adoptPattern(
+              id,
+              args.project
+            );
+            return {
+              content: [{ type: "text", text: JSON.stringify(pattern, null, 2) }]
+            };
+          }
+          case "pattern_suggest": {
+            const response = await this.client.suggestPatterns(
+              args.project,
+              args.limit
+            );
+            return {
+              content: [{ type: "text", text: JSON.stringify(response, null, 2) }]
+            };
+          }
+          case "project_context": {
+            const context = await this.client.getProjectContext(
+              args.project
+            );
+            return {
+              content: [{ type: "text", text: JSON.stringify(context, null, 2) }]
+            };
+          }
+          case "memory_promote": {
+            const id = args.memory_id;
+            validateUuid(id, "memory_id");
+            const updated = await this.client.promoteMemory(
+              id,
+              args.importance,
+              args.tier
+            );
+            return {
+              content: [{ type: "text", text: JSON.stringify(updated, null, 2) }]
+            };
+          }
           default:
             throw new Error(`Unknown tool: ${name}`);
         }
       } catch (error) {
         let errorMessage = "Unknown error";
         let errorDetails = void 0;
-        if (error instanceof z2.ZodError) {
+        if (error instanceof z.ZodError) {
           errorMessage = "Validation error";
           errorDetails = error.errors;
         } else if (error instanceof Error) {
@@ -766,206 +1663,99 @@ var MemoryRelayMCPServer = class {
     });
   }
   /**
-   * Setup MCP resource handlers
+   * Start the MCP server with STDIO transport
    */
-  setupResourceHandlers() {
-    this.server.setRequestHandler(ListResourcesRequestSchema, async () => ({
-      resources: [
-        {
-          uri: "memory:///recent",
-          name: "Recent Memories",
-          description: "The 20 most recent memories stored in MemoryRelay",
-          mimeType: "application/json"
-        }
-      ]
-    }));
-    this.server.setRequestHandler(ListResourceTemplatesRequestSchema, async () => ({
-      resourceTemplates: [
-        {
-          uriTemplate: "memory:///{id}",
-          name: "Memory by ID",
-          description: "Retrieve a specific memory by its UUID",
-          mimeType: "application/json"
-        }
-      ]
-    }));
-    this.server.setRequestHandler(ReadResourceRequestSchema, async (request) => {
-      const { uri } = request.params;
-      try {
-        if (uri === "memory:///recent") {
-          const response = await this.client.listMemories(20, 0);
-          return {
-            contents: [
-              {
-                uri,
-                mimeType: "application/json",
-                text: JSON.stringify(response, null, 2)
-              }
-            ]
-          };
-        }
-        const match = uri.match(/^memory:\/\/\/([0-9a-f-]{36})$/);
-        if (match) {
-          const id = match[1];
-          validateUuid(id, "memory_id");
-          const memory = await this.client.getMemory(id);
-          return {
-            contents: [
-              {
-                uri,
-                mimeType: "application/json",
-                text: JSON.stringify(memory, null, 2)
-              }
-            ]
-          };
-        }
-        throw new Error(`Unknown resource: ${uri}`);
-      } catch (error) {
-        const message = error instanceof Error ? error.message : "Unknown error";
-        this.logger.error(`Resource read failed: ${uri}`, { error: message });
-        throw error;
-      }
-    });
+  async start() {
+    const transport = new StdioServerTransport();
+    await this.server.connect(transport);
+    this.logger.info("MCP server started on STDIO");
   }
   /**
-   * Setup MCP prompt handlers
+   * Connect the MCP server to a custom transport (for testing)
    */
-  setupPromptHandlers() {
-    this.server.setRequestHandler(ListPromptsRequestSchema, async () => ({
-      prompts: [
-        {
-          name: "store_memory",
-          description: "Store information as a persistent memory with appropriate metadata",
-          arguments: [
-            {
-              name: "information",
-              description: "The information to remember",
-              required: true
-            },
-            {
-              name: "category",
-              description: "Category for the memory (e.g., preference, fact, instruction, context)",
-              required: false
-            }
-          ]
-        },
-        {
-          name: "recall_memories",
-          description: "Search for and recall relevant memories about a topic",
-          arguments: [
-            {
-              name: "topic",
-              description: "The topic or question to search memories for",
-              required: true
-            }
-          ]
-        },
-        {
-          name: "summarize_memories",
-          description: "List and summarize all recent memories for context",
-          arguments: []
-        }
-      ]
-    }));
-    this.server.setRequestHandler(GetPromptRequestSchema, async (request) => {
-      const { name, arguments: args } = request.params;
-      switch (name) {
-        case "store_memory": {
-          const information = args?.information ?? "";
-          const category = args?.category ?? "";
-          const metadataInstruction = category ? ` Attach metadata with category "${category}".` : " Attach appropriate metadata with a category tag.";
-          return {
-            messages: [
-              {
-                role: "user",
-                content: {
-                  type: "text",
-                  text: `Please store the following information as a persistent memory using the memory_store tool.${metadataInstruction}
-
-Information to remember:
-${information}`
-                }
-              }
-            ]
-          };
-        }
-        case "recall_memories": {
-          const topic = args?.topic ?? "";
-          return {
-            messages: [
-              {
-                role: "user",
-                content: {
-                  type: "text",
-                  text: `Search my memories for information related to: "${topic}"
-
-Use the memory_search tool to find relevant memories, then summarize what you found. If nothing relevant is found, let me know.`
-                }
-              }
-            ]
-          };
-        }
-        case "summarize_memories": {
-          return {
-            messages: [
-              {
-                role: "user",
-                content: {
-                  type: "text",
-                  text: "List my recent memories using the memory_list tool and provide a brief summary of what has been remembered. Group them by topic or category if possible."
-                }
-              }
-            ]
-          };
-        }
-        default:
-          throw new Error(`Unknown prompt: ${name}`);
-      }
-    });
+  async connectTransport(transport) {
+    await this.server.connect(transport);
   }
   /**
-   * Start the MCP server with STDIO transport
+   * Close the MCP server connection
    */
-  async start() {
-    const transport = new StdioServerTransport();
-    await this.server.connect(transport);
-    this.logger.info("MCP server started on STDIO");
+  async close() {
+    await this.server.close();
   }
 };
 
 // src/index.ts
+async function startServer() {
+  const config = loadConfig();
+  initLogger(config.logLevel);
+  const logger = getLogger();
+  logger.info("Starting MemoryRelay MCP server");
+  const agentId = getAgentId(config);
+  const server = new MemoryRelayMCPServer({
+    apiKey: config.apiKey,
+    apiUrl: config.apiUrl,
+    agentId,
+    timeout: config.timeout
+  });
+  await server.start();
+  process.on("SIGINT", () => {
+    logger.info("Received SIGINT, shutting down gracefully");
+    process.exit(0);
+  });
+  process.on("SIGTERM", () => {
+    logger.info("Received SIGTERM, shutting down gracefully");
+    process.exit(0);
+  });
+}
 async function main() {
+  const command = process.argv[2];
   try {
-    const config = loadConfig();
-    initLogger(config.logLevel);
-    const logger2 = getLogger();
-    logger2.info("Starting MemoryRelay MCP server");
-    const agentId = getAgentId(config);
-    const server = new MemoryRelayMCPServer({
-      apiKey: config.apiKey,
-      apiUrl: config.apiUrl,
-      agentId,
-      timeout: config.timeout
-    });
-    await server.start();
-    process.on("SIGINT", () => {
-      logger2.info("Received SIGINT, shutting down gracefully");
-      process.exit(0);
-    });
-    process.on("SIGTERM", () => {
-      logger2.info("Received SIGTERM, shutting down gracefully");
-      process.exit(0);
-    });
+    switch (command) {
+      case "setup": {
+        const { runSetup } = await import("./cli/setup.js");
+        await runSetup();
+        break;
+      }
+      case "test": {
+        const { runTest } = await import("./cli/test.js");
+        await runTest();
+        break;
+      }
+      case "--help":
+      case "-h": {
+        console.error(`
+  memoryrelay-mcp - Persistent memory for AI agents
+
+  Usage:
+    npx memoryrelay-mcp          Start MCP server (stdio transport)
+    npx memoryrelay-mcp setup    Interactive setup wizard
+    npx memoryrelay-mcp test     Test API connectivity
+    npx memoryrelay-mcp --help   Show this help message
+
+  Environment variables:
+    MEMORYRELAY_API_KEY     API key (required, starts with "mem_")
+    MEMORYRELAY_API_URL     API URL (default: https://api.memoryrelay.net)
+    MEMORYRELAY_AGENT_ID    Agent ID (optional, auto-detected)
+    MEMORYRELAY_TIMEOUT     Request timeout in ms (default: 30000)
+    MEMORYRELAY_LOG_LEVEL   Log level: debug|info|warn|error (default: info)
+
+  Documentation: https://github.com/memoryrelay/mcp-server
+`);
+        break;
+      }
+      default:
+        await startServer();
+    }
   } catch (error) {
-    const logger2 = getLogger();
+    const logger = getLogger();
     if (error instanceof Error) {
-      logger2.error("Fatal error:", { message: error.message });
-      console.error("\n\u274C Failed to start MemoryRelay MCP server\n");
+      logger.error("Fatal error:", { message: error.message });
+      console.error("\nFailed to start MemoryRelay MCP server\n");
       console.error(error.message);
-      console.error("\nFor help, see: https://github.com/memoryrelay/mcp-server#troubleshooting\n");
+      console.error("\nFor help, run: npx memoryrelay-mcp --help\n");
     } else {
-      logger2.error("Fatal error:", { error });
-      console.error("\n\u274C An unexpected error occurred\n");
+      logger.error("Fatal error:", { error });
+      console.error("\nAn unexpected error occurred\n");
     }
     process.exit(1);
   }