Create or update entities with observations
create_entitiesCreate and update knowledge graph entities with observations to build persistent memory for AI assistants using SQLite storage.
Instructions
Create or update entities with observations
Tool call template
Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.
{
"id": 1,
"jsonrpc": "2.0",
"method": "tools/call",
"params": {
"arguments": {
"entities": "<entities>"
},
"name": "create_entities"
}
}Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| entities | Yes |
Implementation Reference
- src/db/client.ts:40-135 (handler)The core database handler function that executes the create_entities logic. Validates input entities, checks if entities exist (upsert), manages observations in a SQL transaction, and performs SQLite operations.
async create_entities( entities: Array<{ name: string; entityType: string; observations: string[]; }>, ): Promise<void> { const transaction = this.db.transaction(() => { for (const entity of entities) { // Validate entity name if ( !entity.name || typeof entity.name !== 'string' || entity.name.trim() === '' ) { throw new Error('Entity name must be a non-empty string'); } // Validate entity type if ( !entity.entityType || typeof entity.entityType !== 'string' || entity.entityType.trim() === '' ) { throw new Error( `Invalid entity type for entity "${entity.name}"`, ); } // Validate observations if ( !Array.isArray(entity.observations) || entity.observations.length === 0 ) { throw new Error( `Entity "${entity.name}" must have at least one observation`, ); } if ( !entity.observations.every( (obs) => typeof obs === 'string' && obs.trim() !== '', ) ) { throw new Error( `Entity "${entity.name}" has invalid observations. All observations must be non-empty strings`, ); } // Check if entity exists const existing = this.db .prepare('SELECT name FROM entities WHERE name = ?') .get(entity.name); if (existing) { // Update existing entity this.db .prepare( 'UPDATE entities SET entity_type = ? WHERE name = ?', ) .run(entity.entityType, entity.name); } else { // Insert new entity this.db .prepare( 'INSERT INTO entities (name, entity_type) VALUES (?, ?)', ) .run(entity.name, entity.entityType); } // Clear old observations this.db .prepare('DELETE FROM observations WHERE entity_name = ?') .run(entity.name); // Add new observations const insert_obs = this.db.prepare( 'INSERT INTO observations (entity_name, content) VALUES (?, ?)', ); for (const observation of entity.observations) { insert_obs.run(entity.name, observation); } } }); try { transaction(); } catch (error) { // Wrap all errors with context throw new Error( `Entity operation failed: ${ error instanceof Error ? error.message : String(error) }`, ); } } - src/index.ts:23-31 (schema)Valibot schema defining the input validation for create_entities tool. Specifies that entities must be an array of objects containing name (string), entityType (string), and observations (array of strings).
const CreateEntitiesSchema = v.object({ entities: v.array( v.object({ name: v.string(), entityType: v.string(), observations: v.array(v.string()), }), ), }); - src/index.ts:64-103 (registration)MCP tool registration for 'create_entities'. Defines the tool name, description, binds the schema, and provides the handler function that calls db.create_entities() and returns success/error responses.
server.tool<typeof CreateEntitiesSchema>( { name: 'create_entities', description: 'Create or update entities with observations', schema: CreateEntitiesSchema, }, async ({ entities }) => { try { await db.create_entities(entities); return { content: [ { type: 'text' as const, text: `Successfully processed ${entities.length} entities (created new or updated existing)`, }, ], }; } 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, }; } }, );