@memoryrelay/mcp-server 0.2.0 → 0.4.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-J5PEZEMN.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", {
-      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/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?limit=${limit}&offset=${offset}`
-    );
-  }
-  /**
-   * Get a specific memory by ID
-   */
-  async getMemory(id) {
-    return this.request("GET", `/v1/memories/${id}`);
-  }
-  /**
-   * Update an existing memory
-   */
-  async updateMemory(id, content, metadata) {
-    this.validateContentSize(content);
-    return this.request("PATCH", `/v1/memories/${id}`, {
-      content,
-      metadata
-    });
-  }
-  /**
-   * Delete a memory
-   */
-  async deleteMemory(id) {
-    await this.request("DELETE", `/v1/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", "/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.2.0"
+        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,962 @@ 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"]
+          }
+        },
+        // ── V2 Async API Tools (60-600x faster) ──
+        {
+          name: "memory_store_async",
+          description: "Store a memory asynchronously using V2 API. Returns immediately (<50ms) with 202 Accepted and a job ID. Background workers generate the embedding. Use memory_status to poll for completion. Prefer this over memory_store for high-throughput or latency-sensitive applications.",
+          inputSchema: {
+            type: "object",
+            properties: {
+              content: {
+                type: "string",
+                description: "The memory content to store. Be specific and include relevant context."
+              },
+              metadata: {
+                type: "object",
+                description: "Optional key-value metadata to attach to the memory",
+                additionalProperties: { type: "string" }
+              },
+              project: {
+                type: "string",
+                description: "Project slug to associate the memory with",
+                maxLength: 100
+              },
+              importance: {
+                type: "number",
+                description: "Memory importance (0.0-1.0). Values >= 0.8 promote to hot tier.",
+                minimum: 0,
+                maximum: 1
+              },
+              tier: {
+                type: "string",
+                description: 'Memory tier override: "hot", "warm", or "cold"',
+                enum: ["hot", "warm", "cold"]
+              },
+              webhook_url: {
+                type: "string",
+                description: "Optional webhook URL to receive completion notification"
+              }
+            },
+            required: ["content"]
+          }
+        },
+        {
+          name: "memory_status",
+          description: "Check the processing status of a memory created via memory_store_async. Poll this endpoint to determine when embedding generation is complete. Status values: pending (waiting for worker), processing (generating embedding), ready (searchable), failed (error occurred).",
+          inputSchema: {
+            type: "object",
+            properties: {
+              memory_id: {
+                type: "string",
+                description: "Memory ID (UUID) to check status for"
+              }
+            },
+            required: ["memory_id"]
+          }
+        },
+        {
+          name: "context_build",
+          description: "Build a ranked context bundle from memories using V2 API with optional AI summarization. Searches for relevant memories, ranks them by composite score, and optionally generates an AI summary. Useful for building token-efficient context windows for LLM prompts. Supports custom LLM endpoints (Ollama, llama.cpp, vLLM, etc.).",
+          inputSchema: {
+            type: "object",
+            properties: {
+              query: {
+                type: "string",
+                description: "Context query describing what information is needed"
+              },
+              max_memories: {
+                type: "number",
+                description: "Maximum number of memories to include (1-100, default 20)",
+                minimum: 1,
+                maximum: 100,
+                default: 20
+              },
+              max_tokens: {
+                type: "number",
+                description: "Token budget for context window (enforces truncation)",
+                minimum: 100,
+                maximum: 128e3
+              },
+              ai_enhanced: {
+                type: "boolean",
+                description: "Enable AI summarization of context (uses LLM)",
+                default: false
+              },
+              search_mode: {
+                type: "string",
+                description: 'Search mode: "semantic", "hybrid", or "keyword"',
+                enum: ["semantic", "hybrid", "keyword"],
+                default: "hybrid"
+              },
+              llm_api_url: {
+                type: "string",
+                description: "Custom LLM API URL for summarization (OpenAI-compatible). Use for local LLMs: Ollama (http://localhost:11434/v1), llama.cpp, vLLM, LM Studio, etc."
+              },
+              llm_model: {
+                type: "string",
+                description: 'Model name for custom LLM (e.g., "mistral", "llama3", "gemma")'
+              },
+              exclude_memory_ids: {
+                type: "array",
+                items: { type: "string" },
+                description: "Memory IDs to exclude (for multi-turn context building)"
+              }
+            },
+            required: ["query"]
+          }
+        },
+        // ── Tool Name Aliases (backward compatibility with OpenClaw plugin) ──
+        {
+          name: "memory_forget",
+          description: "Delete a memory by ID, or search by query to find candidates. Alias for memory_delete. Provide memoryId for direct deletion, or query to search first.",
+          inputSchema: {
+            type: "object",
+            properties: {
+              memoryId: {
+                type: "string",
+                description: "Memory ID to delete"
+              },
+              query: {
+                type: "string",
+                description: "Search query to find memory"
+              }
+            }
+          }
+        },
+        {
+          name: "memory_recall",
+          description: "Search memories using natural language. Alias for memory_search with default project scoping. Returns the most relevant memories based on semantic similarity.",
+          inputSchema: {
+            type: "object",
+            properties: {
+              query: {
+                type: "string",
+                description: "Natural language search query"
+              },
+              limit: {
+                type: "number",
+                description: "Maximum results (1-50). Default 5.",
+                minimum: 1,
+                maximum: 50,
+                default: 5
+              },
+              threshold: {
+                type: "number",
+                description: "Minimum similarity threshold (0-1). Default 0.3.",
+                minimum: 0,
+                maximum: 1,
+                default: 0.3
+              },
+              project: {
+                type: "string",
+                description: "Filter by project slug"
+              },
+              max_tokens: {
+                type: "number",
+                description: "Token budget for context window"
+              }
+            },
+            required: ["query"]
+          }
+        }
+      ];
+      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,99 +1278,601 @@ 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 "agent_list": {
+            const response = await this.client.listAgents(
+              args.limit
+            );
+            return {
+              content: [
+                {
+                  type: "text",
+                  text: JSON.stringify(response, null, 2)
+                }
+              ]
+            };
+          }
+          case "agent_create": {
+            const createSchema = z.object({
+              name: z.string().min(1).max(255),
+              description: z.string().max(1e3).optional()
+            });
+            const validatedInput = createSchema.parse(args);
+            const sanitizedName = sanitizeHtml(validatedInput.name);
+            const agent = await this.client.createAgent(
+              sanitizedName,
+              validatedInput.description
+            );
+            return {
+              content: [
+                {
+                  type: "text",
+                  text: JSON.stringify(agent, null, 2)
+                }
+              ]
+            };
+          }
+          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 = graphSchema.parse(args);
+            const result = await this.client.getEntityNeighborhood(
+              validatedInput.entity_id,
+              validatedInput.depth,
+              validatedInput.max_neighbors
+            );
+            return {
+              content: [
+                {
+                  type: "text",
+                  text: JSON.stringify(result, null, 2)
                 }
               ]
             };
           }
-          case "memory_delete": {
-            const id = args.id;
-            validateUuid(id, "memory_id");
-            await this.client.deleteMemory(id);
+          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(
-                    { success: true, message: "Memory deleted successfully" },
-                    null,
-                    2
-                  )
+                  text: JSON.stringify(result, 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 "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 = entitySchema.parse(args);
-            const sanitizedName = sanitizeHtml(validatedInput.name);
-            const entity = await this.client.createEntity(
-              sanitizedName,
-              validatedInput.type,
-              validatedInput.metadata
+            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(entity, null, 2)
+                  text: JSON.stringify(result, 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 "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 = linkSchema.parse(args);
-            await this.client.linkEntity(
-              validatedInput.entity_id,
-              validatedInput.memory_id,
-              validatedInput.relationship
+            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 {
+              content: [
+                {
+                  type: "text",
+                  text: JSON.stringify(health, null, 2)
+                }
+              ]
+            };
+          }
+          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(
-                    {
-                      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(session, null, 2)
                 }
               ]
             };
           }
-          case "memory_health": {
-            const health = await this.client.healthCheck();
+          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(health, null, 2)
+                  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) }]
+            };
+          }
+          // ── V2 Async API Tool Handlers ──
+          case "memory_store_async": {
+            const response = await this.client.storeMemoryAsync(
+              args.content,
+              args.metadata,
+              args.project,
+              args.importance,
+              args.tier,
+              args.webhook_url
+            );
+            return {
+              content: [{ type: "text", text: JSON.stringify(response, null, 2) }]
+            };
+          }
+          case "memory_status": {
+            const id = args.memory_id;
+            validateUuid(id, "memory_id");
+            const status = await this.client.getMemoryStatus(id);
+            return {
+              content: [{ type: "text", text: JSON.stringify(status, null, 2) }]
+            };
+          }
+          case "context_build": {
+            const result = await this.client.buildContextV2(
+              args.query,
+              {
+                agentId: args.agent_id,
+                maxMemories: args.max_memories,
+                maxTokens: args.max_tokens,
+                aiEnhanced: args.ai_enhanced,
+                rankingVersion: args.ranking_version,
+                searchMode: args.search_mode,
+                llmApiUrl: args.llm_api_url,
+                llmModel: args.llm_model,
+                excludeMemoryIds: args.exclude_memory_ids
+              }
+            );
+            return {
+              content: [{ type: "text", text: JSON.stringify(result, null, 2) }]
+            };
+          }
+          // ── Tool Name Aliases (backward compatibility) ──
+          case "memory_forget": {
+            const id = args.memoryId;
+            const query = args.query;
+            if (id) {
+              await this.client.deleteMemory(id);
+              return {
+                content: [{ type: "text", text: `Memory ${id.slice(0, 8)}... deleted.` }]
+              };
+            } else if (query) {
+              const results = await this.client.searchMemories(query, 1, 0.9);
+              if (results.length === 1) {
+                await this.client.deleteMemory(results[0].memory.id);
+                return {
+                  content: [{ type: "text", text: `Memory ${results[0].memory.id.slice(0, 8)}... deleted (matched query).` }]
+                };
+              }
+              return {
+                content: [{ type: "text", text: `Found ${results.length} matches. Provide memoryId to delete.` }]
+              };
+            }
+            throw new Error("memoryId or query is required");
+          }
+          case "memory_recall": {
+            const results = await this.client.searchMemories(
+              args.query,
+              args.limit ?? 5,
+              args.threshold ?? 0.3,
+              void 0,
+              // use default agent
+              false,
+              false,
+              false,
+              args.max_tokens,
+              args.project
+            );
+            return {
+              content: [{ type: "text", text: JSON.stringify({ memories: results, total: results.length }, 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 +1903,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);
   }