MCP Memory LibSQL

Instructions

Implementation Reference

• src/index.ts:140-169 (registration)

  Registration of the 'search_nodes' tool in the MCP server's ListTools handler, including name, description, and JSON input schema.

    name: 'search_nodes',
    description: 'Search for entities and their relations using text or vector similarity',
    inputSchema: {
      type: 'object',
      properties: {
        query: {
          oneOf: [
            {
              type: 'string',
              description: 'Text search query',
            },
            {
              type: 'array',
              items: {
                type: 'number',
              },
              description: 'Vector for similarity search',
            },
          ],
        },
        includeEmbeddings: {
          type: 'boolean',
          description: 'Whether to include embeddings in the returned entities (default: false)',
        },
      },
      required: [
        'query',
      ],
    },
  },

• src/index.ts:333-354 (handler)

  MCP tool call handler for 'search_nodes': validates input, calls the searchNodes service function, and returns JSON-formatted results.

  case 'search_nodes': {
    // Safely access properties with type assertions for each property
    if (!args.query) {
      throw new McpError(
        ErrorCode.InvalidParams,
        'Missing required parameter: query'
      );
    }
    
    const query = args.query as string | number[];
    const includeEmbeddings = args.includeEmbeddings as boolean || false;
    
    const result = await searchNodes(query, includeEmbeddings);
    return {
      content: [
        {
          type: 'text',
          text: JSON.stringify(result, null, 2),
        },
      ],
    };
  }

• src/services/graph-service.ts:59-201 (handler)

  Core implementation of searchNodes: performs vector similarity search or text search (with embedding fallback), retrieves relations, returns graph result.

  public static async searchNodes(
    query: string | number[],
    includeEmbeddings = false,
  ): Promise<GraphResult> {
    try {
      let entities: Entity[] = [];
  
      if (Array.isArray(query)) {
        // Validate vector query
        if (!query.every((n) => typeof n === 'number')) {
          throw new ValidationError('Vector query must contain only numbers');
        }
        
        // Vector similarity search
        const client = databaseService.getClient();
        const results = await client.execute({
          sql: `
            SELECT e.name
            FROM entities e
            WHERE e.embedding IS NOT NULL
            ORDER BY vector_distance_cos(e.embedding, vector32(?)) ASC
            LIMIT 5
          `,
          args: [JSON.stringify(query)],
        });
        
        // Get full entities with observations
        entities = await Promise.all(
          results.rows.map(async (row: { name: string }) => 
            getEntity(row.name as string, includeEmbeddings)
          )
        );
      } else {
        // Validate text query
        if (typeof query !== 'string') {
          throw new ValidationError('Text query must be a string');
        }
        if (query.trim() === '') {
          throw new ValidationError('Text query cannot be empty');
        }
        
        try {
          // Try semantic search first by generating an embedding for the text query
          logger.info(`Generating embedding for text query: "${query}"`);
          const embedding = await embeddingService.generateEmbedding(query);
          
          // Vector similarity search using the generated embedding
          logger.info(`Performing semantic search with generated embedding`);
          const client = databaseService.getClient();
          const results = await client.execute({
            sql: `
              SELECT e.name
              FROM entities e
              WHERE e.embedding IS NOT NULL
              ORDER BY vector_distance_cos(e.embedding, vector32(?)) ASC
              LIMIT 5
            `,
            args: [JSON.stringify(embedding)],
          });
          
          // Get full entities with observations
          entities = await Promise.all(
            results.rows.map(async (row: { name: string }) => 
              getEntity(row.name as string, includeEmbeddings)
            )
          );
          
          // If we got results, return them
          if (entities.length > 0) {
            logger.info(`Found ${entities.length} entities via semantic search`);
          } else {
            // Fall back to text search if no results from semantic search
            logger.info(`No results from semantic search, falling back to text search`);
            
            // Text-based search
            const client = databaseService.getClient();
            const results = await client.execute({
              sql: `
                SELECT DISTINCT e.name
                FROM entities e
                LEFT JOIN observations o ON e.name = o.entity_name
                WHERE e.name LIKE ? OR e.entity_type LIKE ? OR o.content LIKE ?
                LIMIT 5
              `,
              args: [`%${query}%`, `%${query}%`, `%${query}%`],
            });
            
            // Get full entities with observations
            entities = await Promise.all(
              results.rows.map(async (row: { name: string }) => 
                getEntity(row.name as string, includeEmbeddings)
              )
            );
          }
        } catch (embeddingError) {
          // If embedding generation fails, fall back to text search
          logger.error(`Failed to generate embedding for query, falling back to text search:`, embeddingError);
          
          // Text-based search
          const client = databaseService.getClient();
          const results = await client.execute({
            sql: `
              SELECT DISTINCT e.name
              FROM entities e
              LEFT JOIN observations o ON e.name = o.entity_name
              WHERE e.name LIKE ? OR e.entity_type LIKE ? OR o.content LIKE ?
              LIMIT 5
            `,
            args: [`%${query}%`, `%${query}%`, `%${query}%`],
          });
          
          // Get full entities with observations
          entities = await Promise.all(
            results.rows.map(async (row: { name: string }) => 
              getEntity(row.name as string, includeEmbeddings)
            )
          );
        }
      }
  
      // If no entities found, return empty graph
      if (entities.length === 0) {
        return { entities: [], relations: [] };
      }
  
      // Get entity names
      const entityNames = entities.map((entity: Entity) => entity.name);
      
      // Get relations for these entities
      const relations = await getRelationsForEntities(entityNames);
      
      // Return graph result
      return { entities, relations };
    } catch (error) {
      if (error instanceof ValidationError) {
        throw error;
      }
      
      throw new DatabaseError(
        `Node search failed: ${error instanceof Error ? error.message : String(error)}`
      );
    }
  }

• src/db/core.ts:288-293 (helper)

  Wrapper method in DatabaseManager that delegates to the searchNodes service function.

  async search_nodes(
  	query: string | number[],
  	includeEmbeddings: boolean = false,
  ): Promise<{ entities: Entity[]; relations: Relation[] }> {
  	return searchNodes(query, includeEmbeddings);
  }

• src/index.ts:281-284 (schema)

  TypeScript interface defining input for search_nodes tool handler.

  interface SearchNodesInput {
    query: string | number[];
    includeEmbeddings?: boolean;
  }