MCP Memory SQLite

Instructions

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,
  			};
  		}
  	},
  );