semantic_search
Search for entities in your knowledge graph memory using semantic meaning and vector similarity to find relevant information based on conceptual relationships.
Instructions
Search for entities semantically using vector embeddings and similarity in your Memento MCP knowledge graph memory
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| query | Yes | The text query to search for semantically | |
| limit | No | Maximum number of results to return (default: 10) | |
| min_similarity | No | Minimum similarity threshold from 0.0 to 1.0 (default: 0.6) | |
| entity_types | No | Filter results by entity types | |
| hybrid_search | No | Whether to combine keyword and semantic search (default: true) | |
| semantic_weight | No | Weight of semantic results in hybrid search from 0.0 to 1.0 (default: 0.6) |
Implementation Reference
- MCP tool handler case for 'semantic_search' that parses input parameters, sets semantic search options, and delegates to KnowledgeGraphManager.search method.case 'semantic_search': try { // Extract search options from args const searchOptions = { limit: args.limit || 10, minSimilarity: args.min_similarity || 0.6, entityTypes: args.entity_types || [], hybridSearch: args.hybrid_search !== undefined ? args.hybrid_search : true, semanticWeight: args.semantic_weight || 0.6, semanticSearch: true, }; // Call the search method with semantic search options const results = await knowledgeGraphManager.search(String(args.query), searchOptions); return { content: [{ type: 'text', text: JSON.stringify(results, null, 2) }] }; } catch (error: Error | unknown) { const errorMessage = error instanceof Error ? error.message : String(error); return { content: [{ type: 'text', text: `Error performing semantic search: ${errorMessage}` }], }; }
- Tool schema definition including name, description, and inputSchema for the semantic_search tool in the MCP tools list.{ name: 'semantic_search', description: 'Search for entities semantically using vector embeddings and similarity in your Memento MCP knowledge graph memory', inputSchema: { type: 'object', properties: { query: { type: 'string', description: 'The text query to search for semantically', }, limit: { type: 'number', description: 'Maximum number of results to return (default: 10)', }, min_similarity: { type: 'number', description: 'Minimum similarity threshold from 0.0 to 1.0 (default: 0.6)', }, entity_types: { type: 'array', items: { type: 'string' }, description: 'Filter results by entity types', }, hybrid_search: { type: 'boolean', description: 'Whether to combine keyword and semantic search (default: true)', }, semantic_weight: { type: 'number', description: 'Weight of semantic results in hybrid search from 0.0 to 1.0 (default: 0.6)', }, }, required: ['query'], }, },
- src/KnowledgeGraphManager.ts:903-979 (handler)Core search method in KnowledgeGraphManager that handles semantic_search tool logic by checking options, generating query embeddings, and delegating to storageProvider.semanticSearch or fallback implementations.async search( query: string, options: { semanticSearch?: boolean; hybridSearch?: boolean; limit?: number; threshold?: number; minSimilarity?: number; entityTypes?: string[]; facets?: string[]; offset?: number; } = {} ): Promise<KnowledgeGraph> { // If hybridSearch is true, always set semanticSearch to true as well if (options.hybridSearch) { options = { ...options, semanticSearch: true }; } // Check if semantic search is requested if (options.semanticSearch || options.hybridSearch) { // Check if we have a storage provider with semanticSearch method if (this.storageProvider && hasSemanticSearch(this.storageProvider)) { try { // Generate query vector if we have an embedding service if (this.embeddingJobManager) { const embeddingService = this.embeddingJobManager['embeddingService']; if (embeddingService) { const queryVector = await embeddingService.generateEmbedding(query); return this.storageProvider.semanticSearch(query, { ...options, queryVector, }); } } // Fall back to text search if no embedding service return this.storageProvider.searchNodes(query); } catch (error) { logger.error('Provider semanticSearch failed, falling back to basic search', error); return this.storageProvider.searchNodes(query); } } else if (this.storageProvider) { // Fall back to searchNodes if semanticSearch is not available in the provider return this.storageProvider.searchNodes(query); } // If no storage provider or its semanticSearch is not available, try internal semantic search if (this.embeddingJobManager) { try { // Try to use semantic search const results = await this.semanticSearch(query, { hybridSearch: options.hybridSearch || false, limit: options.limit || 10, threshold: options.threshold || options.minSimilarity || 0.5, entityTypes: options.entityTypes || [], facets: options.facets || [], offset: options.offset || 0, }); return results; } catch (error) { // Log error but fall back to basic search logger.error('Semantic search failed, falling back to basic search', error); // Explicitly call searchNodes if available in the provider if (this.storageProvider) { return (this.storageProvider as StorageProvider).searchNodes(query); } } } else { logger.warn('Semantic search requested but no embedding capability available'); } } // Use basic search return this.searchNodes(query); }
- src/KnowledgeGraphManager.ts:40-47 (helper)Type guard function to check if the storage provider supports semanticSearch method.function hasSemanticSearch( provider: StorageProvider ): provider is StorageProviderWithSemanticSearch { return ( 'semanticSearch' in provider && typeof (provider as StorageProviderWithSemanticSearch).semanticSearch === 'function' ); }
- src/server/setup.ts:33-36 (registration)Registers the MCP ListTools and CallTool request handlers which expose and execute the semantic_search tool.server.setRequestHandler(ListToolsRequestSchema, async (_request) => { try { const result = await handleListToolsRequest(); return result;