memento-mcp

Instructions

Implementation Reference

• src/server/handlers/callToolHandler.ts:384-452 (handler)

  Main handler for the 'get_entity_embedding' MCP tool. Validates entity existence, retrieves embedding from storage provider, formats response with vector, model, dimensions, and timestamp.

  case 'get_entity_embedding':
    try {
      // Check if entity exists
      const entity = await knowledgeGraphManager.openNodes([String(args.entity_name)]);
      if (!entity.entities || entity.entities.length === 0) {
        return { content: [{ type: 'text', text: `Entity not found: ${args.entity_name}` }] };
      }
  
      // Access the embedding using appropriate interface
      if (
        knowledgeGraphManager.storageProvider &&
        typeof (knowledgeGraphManager.storageProvider as Record<string, unknown>)
          .getEntityEmbedding === 'function'
      ) {
        type EntityEmbedding = {
          vector: number[];
          model?: string;
          lastUpdated?: number;
        };
  
        const embedding = await (
          knowledgeGraphManager.storageProvider as Record<
            string,
            (entityName: string) => Promise<EntityEmbedding | null>
          >
        ).getEntityEmbedding(String(args.entity_name));
  
        if (!embedding) {
          return {
            content: [
              { type: 'text', text: `No embedding found for entity: ${args.entity_name}` },
            ],
          };
        }
  
        return {
          content: [
            {
              type: 'text',
              text: JSON.stringify(
                {
                  entityName: args.entity_name,
                  embedding: embedding.vector,
                  model: embedding.model || 'unknown',
                  dimensions: embedding.vector ? embedding.vector.length : 0,
                  lastUpdated: embedding.lastUpdated || Date.now(),
                },
                null,
                2
              ),
            },
          ],
        };
      } else {
        return {
          content: [
            {
              type: 'text',
              text: `Embedding retrieval not supported by this storage provider`,
            },
          ],
        };
      }
    } catch (error: Error | unknown) {
      const errorMessage = error instanceof Error ? error.message : String(error);
      return {
        content: [{ type: 'text', text: `Error retrieving entity embedding: ${errorMessage}` }],
      };
    }

• src/server/handlers/listToolsHandler.ts:389-403 (schema)

  Tool schema definition including name, description, and input schema requiring 'entity_name' parameter.

  {
    name: 'get_entity_embedding',
    description:
      'Get the vector embedding for a specific entity from your Memento MCP knowledge graph memory',
    inputSchema: {
      type: 'object',
      properties: {
        entity_name: {
          type: 'string',
          description: 'The name of the entity to get the embedding for',
        },
      },
      required: ['entity_name'],
    },
  },

• src/storage/neo4j/Neo4jStorageProvider.ts:1745-1786 (helper)

  Core implementation of getEntityEmbedding method in Neo4jStorageProvider. Queries Neo4j directly for the entity's embedding vector stored on the Entity node.

  async getEntityEmbedding(entityName: string): Promise<EntityEmbedding | null> {
    try {
      // Verify that the entity exists
      const entity = await this.getEntity(entityName);
      if (!entity) {
        logger.debug(`Entity not found when retrieving embedding: ${entityName}`);
        return null;
      }
  
      const session = await this.connectionManager.getSession();
  
      try {
        // Query to get the entity with its embedding
        const query = `
          MATCH (e:Entity {name: $name})
          WHERE e.validTo IS NULL
          RETURN e.embedding AS embedding
        `;
  
        const result = await session.run(query, { name: entityName });
  
        if (result.records.length === 0 || !result.records[0].get('embedding')) {
          logger.debug(`No embedding found for entity: ${entityName}`);
          return null;
        }
  
        const embeddingVector = result.records[0].get('embedding');
  
        // Return the embedding in the expected format
        return {
          vector: embeddingVector,
          model: 'unknown', // We don't store the model info in Neo4j
          lastUpdated: entity.updatedAt || Date.now(),
        };
      } finally {
        await session.close();
      }
    } catch (error) {
      logger.error(`Error retrieving embedding for entity ${entityName} from Neo4j`, error);
      return null;
    }
  }