mcp-memory-libsql

Instructions

Implementation Reference

• src/index.ts:102-141 (handler)

  MCP server tool handler for 'search_nodes': validates input, calls db.search_nodes(query, limit), returns JSON result or error.
  server.tool<typeof SearchNodesSchema>( { name: 'search_nodes', description: 'Search for entities and their relations using text search with relevance ranking', schema: SearchNodesSchema, }, async ({ query, limit }) => { try { const result = await db.search_nodes(query, limit); return { content: [ { type: 'text' as const, text: JSON.stringify(result, null, 2), }, ], }; } catch (error) { return { content: [ { type: 'text' as const, text: JSON.stringify( { error: 'internal_error', message: error instanceof Error ? error.message : 'Unknown error', }, null, 2, ), }, ], isError: true, }; } },
• src/index.ts:33-36 (schema)

  Valibot schema definition for search_nodes tool input: query (required string), limit (optional number).
  const SearchNodesSchema = v.object({ query: v.string(), limit: v.optional(v.number()), });
• src/index.ts:102-141 (registration)

  Registration of 'search_nodes' tool on the MCP server within setupTools function.
  server.tool<typeof SearchNodesSchema>( { name: 'search_nodes', description: 'Search for entities and their relations using text search with relevance ranking', schema: SearchNodesSchema, }, async ({ query, limit }) => { try { const result = await db.search_nodes(query, limit); return { content: [ { type: 'text' as const, text: JSON.stringify(result, null, 2), }, ], }; } catch (error) { return { content: [ { type: 'text' as const, text: JSON.stringify( { error: 'internal_error', message: error instanceof Error ? error.message : 'Unknown error', }, null, 2, ), }, ], isError: true, }; } },
• src/db/client.ts:367-399 (helper)

  DatabaseManager.search_nodes: core logic searches entities using text query with relevance, fetches associated relations.
  async search_nodes( query: string, limit?: number, ): Promise<{ entities: Entity[]; relations: Relation[] }> { try { // Validate text query if (typeof query !== 'string') { throw new Error('Text query must be a string'); } if (query.trim() === '') { throw new Error('Text query cannot be empty'); } // Text-based search with optional limit const entities = await this.search_entities(query, limit); // If no entities found, return empty result if (entities.length === 0) { return { entities: [], relations: [] }; } const relations = await this.get_relations_for_entities( entities, ); return { entities, relations }; } catch (error) { throw new Error( `Node search failed: ${ error instanceof Error ? error.message : String(error) }`, ); } }
• src/db/client.ts:156-210 (helper)

  DatabaseManager.search_entities: performs fuzzy text search on entities, types, observations with relevance scoring.
  async search_entities( query: string, limit: number = 10, ): Promise<Entity[]> { // Normalize query for fuzzy matching const normalized_query = `%${query.replace(/[\s_-]+/g, '%')}%`; const results = await this.client.execute({ sql: ` SELECT DISTINCT e.name, e.entity_type, e.created_at, CASE WHEN e.name LIKE ? COLLATE NOCASE THEN 3 WHEN e.entity_type LIKE ? COLLATE NOCASE THEN 2 ELSE 1 END as relevance_score FROM entities e LEFT JOIN observations o ON e.name = o.entity_name WHERE e.name LIKE ? COLLATE NOCASE OR e.entity_type LIKE ? COLLATE NOCASE OR o.content LIKE ? COLLATE NOCASE ORDER BY relevance_score DESC, e.created_at DESC LIMIT ? `, args: [ normalized_query, normalized_query, normalized_query, normalized_query, normalized_query, limit > 50 ? 50 : limit, // Cap at 50 ], }); const entities: Entity[] = []; for (const row of results.rows) { const name = row.name as string; const observations = await this.client.execute({ sql: 'SELECT content FROM observations WHERE entity_name = ?', args: [name], }); entities.push({ name, entityType: row.entity_type as string, observations: observations.rows.map( (obs) => obs.content as string, ), }); } return entities; }