MCP Memory LibSQL

Instructions

Implementation Reference

• src/services/entity-service.ts:17-100 (handler)

  Core handler function that creates or updates entities with observations, generates embeddings if needed, manages database transactions, and handles relations.
  public static async createEntities(entities: EntityCreateParams[]): Promise<void> { try { const client = databaseService.getClient(); for (const entity of entities) { // Validate entity if (!entity.name || typeof entity.name !== 'string' || entity.name.trim() === '') { throw new ValidationError('Entity name must be a non-empty string'); } if (!entity.entityType || typeof entity.entityType !== 'string' || entity.entityType.trim() === '') { throw new ValidationError(`Invalid entity type for entity "${entity.name}"`); } if (!Array.isArray(entity.observations) || entity.observations.length === 0) { throw new ValidationError(`Entity "${entity.name}" must have at least one observation`); } // Generate embedding if not provided let embedding = entity.embedding; if (!embedding) { try { logger.info(`Generating embedding for entity: ${entity.name}`); const text = entity.observations.join(' '); embedding = await embeddingService.generateEmbedding(text); } catch (error) { logger.error(`Failed to generate embedding for entity "${entity.name}":`, error); } } // Use a transaction for entity and observations await databaseService.transaction(async (txn) => { const vectorString = arrayToVectorString(embedding); // First try to update const result = await txn.execute({ sql: 'UPDATE entities SET entity_type = ?, embedding = vector32(?) WHERE name = ?', args: [entity.entityType, vectorString, entity.name], }); // If no rows affected, do insert if (result.rowsAffected === 0) { await txn.execute({ sql: 'INSERT INTO entities (name, entity_type, embedding) VALUES (?, ?, vector32(?))', args: [entity.name, entity.entityType, vectorString], }); } // Clear old observations await txn.execute({ sql: 'DELETE FROM observations WHERE entity_name = ?', args: [entity.name], }); // Add new observations for (const observation of entity.observations) { await txn.execute({ sql: 'INSERT INTO observations (entity_name, content) VALUES (?, ?)', args: [entity.name, observation], }); } }); // Handle relations if provided if (entity.relations && entity.relations.length > 0) { const relations = entity.relations.map(rel => ({ from: entity.name, to: rel.target, relationType: rel.relationType })); await EntityService.createRelations(relations); } } } catch (error) { if (error instanceof Error && error.message.includes('SQLITE_CONSTRAINT')) { throw parseDatabaseError(error); } throw new DatabaseError( `Entity operation failed: ${error instanceof Error ? error.message : String(error)}` ); } }
• src/index.ts:79-137 (schema)

  Input schema for the create_entities tool defining the expected structure of the entities array parameter.
  inputSchema: { type: 'object', properties: { entities: { type: 'array', items: { type: 'object', properties: { name: { type: 'string', }, entityType: { type: 'string', }, observations: { type: 'array', items: { type: 'string', }, }, embedding: { type: 'array', items: { type: 'number', }, description: 'Optional vector embedding for similarity search', }, relations: { type: 'array', items: { type: 'object', properties: { target: { type: 'string', }, relationType: { type: 'string', }, }, required: [ 'target', 'relationType', ], }, description: 'Optional relations to create with this entity', }, }, required: [ 'name', 'entityType', 'observations', ], }, }, }, required: [ 'entities', ], },
• src/index.ts:76-138 (registration)

  Tool registration in the listTools response, including name, description, and input schema.
  { name: 'create_entities', description: 'Create new entities with observations and optional embeddings', inputSchema: { type: 'object', properties: { entities: { type: 'array', items: { type: 'object', properties: { name: { type: 'string', }, entityType: { type: 'string', }, observations: { type: 'array', items: { type: 'string', }, }, embedding: { type: 'array', items: { type: 'number', }, description: 'Optional vector embedding for similarity search', }, relations: { type: 'array', items: { type: 'object', properties: { target: { type: 'string', }, relationType: { type: 'string', }, }, required: [ 'target', 'relationType', ], }, description: 'Optional relations to create with this entity', }, }, required: [ 'name', 'entityType', 'observations', ], }, }, }, required: [ 'entities', ], }, },
• src/index.ts:307-331 (handler)

  Dispatch handler in callTool request that validates arguments and invokes the createEntities implementation.
  case 'create_entities': { // Define the expected type for entities interface EntityInput { name: string; entityType: string; observations: string[]; embedding?: number[]; relations?: Array<{ target: string; relationType: string; }>; } // Type assertion with proper interface const entities = args.entities as EntityInput[]; await createEntities(entities); return { content: [ { type: 'text', text: `Successfully processed ${entities.length} entities (created new or updated existing)`, }, ], }; }
• src/services/entity-service.ts:269-269 (helper)

  Exports the static method as a convenience function for use in other modules.
  export const createEntities = EntityService.createEntities;