Memory Box MCP Server

Instructions

Implementation Reference

• src/index.ts:903-951 (handler)

  The main handler for the 'search_memories' tool. Parses input arguments, validates the query, calls the MemoryBoxClient.searchMemories method with options, formats the search results into a readable text response including similarity scores and optional debug info, and returns it.
  case "search_memories": { const query = String(request.params.arguments?.query || ""); if (!query) { throw new McpError(ErrorCode.InvalidParams, "Query is required"); } const options = { bucketId: request.params.arguments?.bucket_id ? String(request.params.arguments.bucket_id) : undefined, sourceType: request.params.arguments?.source_type ? String(request.params.arguments.source_type) : undefined, limit: request.params.arguments?.limit ? Number(request.params.arguments.limit) : undefined, offset: request.params.arguments?.offset ? Number(request.params.arguments.offset) : undefined, debug: Boolean(request.params.arguments?.debug || false), includeReferenceData: Boolean(request.params.arguments?.include_reference_data || false), dateSort: Boolean(request.params.arguments?.date_sort || false), sortOrder: request.params.arguments?.sort_order as 'asc' | 'desc' | undefined }; // Search memories const result = await memoryBoxClient.searchMemories(query, options); // Format the results let responseText = `Search results for "${query}":\n\n`; if (result.items && result.items.length > 0) { result.items.forEach((memory: any, index: number) => { const similarity = memory.similarity ? ` (${Math.round(memory.similarity * 100)}% match)` : ""; responseText += `${index + 1}. ${similarity} ${memory.text}\n\n`; }); } else { responseText += "No memories found matching your query."; } // Add debug information if requested if (options.debug && result.debug) { responseText += "\n\nDebug Information:\n"; responseText += `Query: ${result.debug.query}\n`; responseText += `Query Terms: ${result.debug.query_terms.join(", ")}\n`; responseText += `Threshold: ${result.debug.threshold}\n`; responseText += `All Results: ${result.debug.all_results.length}\n`; } return { content: [{ type: "text", text: responseText }] }; }
• src/index.ts:608-657 (schema)

  Input schema definition for the 'search_memories' tool, specifying parameters such as query (required), filters, pagination, and sorting options with types and descriptions.
  { name: "search_memories", description: "Search for memories using semantic search", inputSchema: { type: "object", properties: { query: { type: "string", description: "The search query (semantic search)" }, bucket_id: { type: "string", description: "Filter to specific bucket" }, source_type: { type: "string", description: "Filter by source type" }, limit: { type: "integer", description: "Maximum number of results to return (1-100, default: 10)", minimum: 1, maximum: 100 }, offset: { type: "integer", description: "Number of results to skip for pagination (default: 0)", minimum: 0 }, debug: { type: "boolean", description: "Include debug information in results (default: false)" }, include_reference_data: { type: "boolean", description: "Include reference data in response (default: false)" }, date_sort: { type: "boolean", description: "Sort semantic search results by date after similarity filtering (default: false)" }, sort_order: { type: "string", description: "Sort order when date_sort is enabled (default: 'desc')", enum: ["asc", "desc"] } }, required: ["query"] } },
• src/index.ts:160-206 (helper)

  MemoryBoxClient helper method that constructs query parameters from options and makes the HTTP GET request to the Memory Box API /api/v2/memory endpoint for semantic search, handling errors with McpError.
  async searchMemories( query: string, options?: { bucketId?: string; sourceType?: string; limit?: number; offset?: number; debug?: boolean; includeReferenceData?: boolean; dateSort?: boolean; sortOrder?: 'asc' | 'desc'; } ): Promise<any> { try { const params: any = { query }; if (options) { if (options.bucketId !== undefined) params.bucketId = options.bucketId; if (options.sourceType !== undefined) params.source_type = options.sourceType; if (options.limit !== undefined) params.limit = options.limit; if (options.offset !== undefined) params.offset = options.offset; if (options.debug !== undefined) params.debug = options.debug; if (options.includeReferenceData !== undefined) params.include_reference_data = options.includeReferenceData; if (options.dateSort !== undefined) params.date_sort = options.dateSort; if (options.sortOrder !== undefined) params.sort_order = options.sortOrder; } const response = await axios.get( `${this.baseUrl}/api/v2/memory`, { params, headers: { "Authorization": `Bearer ${this.token}` } } ); return response.data; } catch (error) { if (axios.isAxiosError(error)) { throw new McpError( ErrorCode.InternalError, `Failed to search memories: ${error.response?.data?.detail || error.message}` ); } throw error; } }
• src/index.ts:543-866 (registration)

  The ListToolsRequestHandler registers the 'search_memories' tool by including it in the returned tools list with its name, description, and inputSchema.
  server.setRequestHandler(ListToolsRequestSchema, async () => { return { tools: [ { name: "save_memory", description: "Save a memory to Memory Box", inputSchema: { type: "object", properties: { text: { type: "string", description: "The memory content to save (either text OR raw_content required)" }, raw_content: { type: "string", description: "Raw content for processing (alternative to text)" }, bucket_id: { type: "string", description: `The bucket to save the memory to (default: "${DEFAULT_BUCKET}")` }, source_type: { type: "string", description: "Type of memory source (default: 'llm_plugin')" }, reference_data: { type: "object", description: "Structured metadata for memory storage", properties: { source: { type: "object", required: ["platform"], properties: { platform: { type: "string", description: "Platform identifier (required)" }, type: { type: "string", description: "Source type" }, version: { type: "string", description: "Version info" }, url: { type: "string", description: "Source URL" }, title: { type: "string", description: "Source title" }, additional_metadata: { type: "object", description: "Extra metadata" } } }, context: { type: "object", properties: { related_memories: { type: "array", items: { type: "object" }, description: "Related memory references" }, conversation_id: { type: "string", description: "Conversation identifier" }, message_id: { type: "string", description: "Message identifier" } } }, content_context: { type: "object", properties: { url: { type: "string", description: "Content URL" }, title: { type: "string", description: "Content title" }, surrounding_text: { type: "string", description: "Context around selection" }, selected_text: { type: "string", description: "Selected text" }, additional_context: { type: "object", description: "Extra context" } } } } } }, required: ["text"] } }, { name: "search_memories", description: "Search for memories using semantic search", inputSchema: { type: "object", properties: { query: { type: "string", description: "The search query (semantic search)" }, bucket_id: { type: "string", description: "Filter to specific bucket" }, source_type: { type: "string", description: "Filter by source type" }, limit: { type: "integer", description: "Maximum number of results to return (1-100, default: 10)", minimum: 1, maximum: 100 }, offset: { type: "integer", description: "Number of results to skip for pagination (default: 0)", minimum: 0 }, debug: { type: "boolean", description: "Include debug information in results (default: false)" }, include_reference_data: { type: "boolean", description: "Include reference data in response (default: false)" }, date_sort: { type: "boolean", description: "Sort semantic search results by date after similarity filtering (default: false)" }, sort_order: { type: "string", description: "Sort order when date_sort is enabled (default: 'desc')", enum: ["asc", "desc"] } }, required: ["query"] } }, { name: "get_all_memories", description: "Retrieve all memories with pagination support", inputSchema: { type: "object", properties: { all: { type: "boolean", description: "Get all memories (overrides pagination, default: false)" }, bucket_id: { type: "string", description: "Filter to specific bucket" }, source_type: { type: "string", description: "Filter by source type" }, limit: { type: "integer", description: "Maximum number of results to return (1-100, default: 10)", minimum: 1, maximum: 100 }, offset: { type: "integer", description: "Number of results to skip for pagination (default: 0)", minimum: 0 }, include_reference_data: { type: "boolean", description: "Include reference data in response (default: false)" }, date_sort: { type: "boolean", description: "Sort results by date (default: false)" }, sort_order: { type: "string", description: "Sort order (default: 'desc')", enum: ["asc", "desc"] } } } }, { name: "get_bucket_memories", description: "Get memories from a specific bucket", inputSchema: { type: "object", properties: { bucket_id: { type: "string", description: "The bucket to retrieve memories from" }, limit: { type: "integer", description: "Maximum number of results to return (1-100, default: 10)", minimum: 1, maximum: 100 }, offset: { type: "integer", description: "Number of results to skip for pagination (default: 0)", minimum: 0 }, include_reference_data: { type: "boolean", description: "Include reference data in response (default: false)" } }, required: ["bucket_id"] } }, { name: "get_related_memories", description: "Find semantically similar memories to a specific memory", inputSchema: { type: "object", properties: { memory_id: { type: "integer", description: "The ID of the memory to find related memories for" }, min_similarity: { type: "number", description: "Minimum similarity threshold (0.0-1.0) for related memories (default: 0.7)" } }, required: ["memory_id"] } }, { name: "check_memory_status", description: "Check the processing status of a memory", inputSchema: { type: "object", properties: { memory_id: { type: "integer", description: "The ID of the memory to check status for" } }, required: ["memory_id"] } }, { name: "get_usage_stats", description: "Retrieve user usage statistics and plan information", inputSchema: { type: "object", properties: { // No specific parameters needed for this operation } } }, { name: "get_buckets", description: "Retrieve a list of all available buckets", inputSchema: { type: "object", properties: { // No specific parameters needed for this operation } } }, { name: "create_bucket", description: "Create a new bucket for organizing memories", inputSchema: { type: "object", properties: { bucket_name: { type: "string", description: "Name of the bucket to create" } }, required: ["bucket_name"] } }, { name: "delete_bucket", description: "Delete a bucket (empty by default, use force to delete with content)", inputSchema: { type: "object", properties: { bucket_name: { type: "string", description: "Name of the bucket to delete" }, force: { type: "boolean", description: "Force deletion even if bucket contains memories (default: false)" } }, required: ["bucket_name"] } }, { name: "update_memory", description: "Update an existing memory including text, bucket, and relationships", inputSchema: { type: "object", properties: { memory_id: { type: "integer", description: "The ID of the memory to update" }, text: { type: "string", description: "New text content for the memory" }, raw_content: { type: "string", description: "New raw content for the memory" }, bucket_id: { type: "string", description: "Move memory to different bucket" }, source_type: { type: "string", description: "Update source type" }, reference_data: { type: "object", description: "Updated reference data (same structure as save_memory)" } }, required: ["memory_id"] } }, { name: "delete_memory", description: "Delete a specific memory", inputSchema: { type: "object", properties: { memory_id: { type: "integer", description: "The ID of the memory to delete" } }, required: ["memory_id"] } } ] }; });