create_entities
Generate new entities, add observations, optional embeddings, and define relations for efficient knowledge storage and vector search within the MCP Memory LibSQL system.
Instructions
Create new entities with observations and optional embeddings
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| entities | Yes |
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)`, }, ], }; } - Exports the static method as a convenience function for use in other modules.
export const createEntities = EntityService.createEntities;