add_observations
Enhance knowledge graph entities by adding new observations to their data, enabling structured updates for improved reasoning and analysis in the MCP Think Tank server.
Instructions
Add new observations to existing entities in the knowledge graph
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| observations | Yes | Array of entity observations to add |
Input Schema (JSON Schema)
{
"$schema": "http://json-schema.org/draft-07/schema#",
"additionalProperties": false,
"properties": {
"observations": {
"description": "Array of entity observations to add",
"items": {
"additionalProperties": false,
"properties": {
"contents": {
"description": "Observations to add to the entity",
"items": {
"type": "string"
},
"type": "array"
},
"entityName": {
"description": "Name of the entity to add observations to",
"minLength": 1,
"type": "string"
}
},
"required": [
"entityName",
"contents"
],
"type": "object"
},
"type": "array"
}
},
"required": [
"observations"
],
"type": "object"
}
Implementation Reference
- src/memory/tools.ts:209-248 (handler)The execute handler for the 'add_observations' tool. Loops through provided observations, calls memoryStore.add for each, collects results, saves changes, and returns JSON summary.execute: async (args) => { const results = { updated: [] as Array<{entityName: string, added: string[]}>, failed: [] as Array<{entityName: string, reason: string}> }; for (const item of args.observations) { try { const added: string[] = []; for (const content of item.contents) { await memoryStore.add(item.entityName, content, { version: '1.0' }); added.push(content); } if (added.length > 0) { results.updated.push({ entityName: item.entityName, added }); } } catch (error) { results.failed.push({ entityName: item.entityName, reason: `Failed to add observations: ${error}` }); } } // Save changes await memoryStore.save(); // Return as string return JSON.stringify({ updated: results.updated.length > 0 ? results.updated : null, failed: results.failed.length > 0 ? results.failed : null, message: `Added observations to ${results.updated.length} entities. Failed for ${results.failed.length} entities.` }); }
- src/memory/tools.ts:205-208 (registration)Registration of the 'add_observations' MCP tool on the FastMCP server, specifying name, description, and schema.server.addTool({ name: 'add_observations', description: 'Add new observations to existing entities in the knowledge graph', parameters: Schemas.AddObservationsSchema,
- src/utils/validation.ts:35-40 (schema)Zod schema definition for validating inputs to the add_observations tool.export const AddObservationsSchema = z.object({ observations: z.array(z.object({ entityName: z.string().min(1).describe('Name of the entity to add observations to'), contents: z.array(z.string()).describe('Observations to add to the entity') })).describe('Array of entity observations to add') });
- Low-level helper method in JsonlMemoryStore that actually adds an observation to an entity, updates the graph, handles auto-linking, and persists to JSONL file. Called by the tool handler.async add(entityName: string, text: string, metadata?: { version?: string; tags?: string[]; agent?: string; }): Promise<Observation> { await this.getLoadingPromise(); // Create observation with timestamp const observation: Observation = { text, timestamp: new Date().toISOString(), version: metadata?.version }; // Get entity or create if it doesn't exist let entity = this.enhancedEntities.get(entityName); let isNewEntity = false; if (!entity) { entity = { name: entityName, entityType: 'default', // Default type if entity doesn't exist observations: [] }; this.enhancedEntities.set(entityName, entity); isNewEntity = true; // Also add to the graph for backward compatibility this.graph.addEntity({ name: entityName, entityType: 'default', observations: [] }); } // Add observation to entity entity.observations.push(observation); // Update graph for backward compatibility this.graph.addObservations(entityName, [text]); // If this is a new entity and auto-linking is enabled, create relationships if (isNewEntity && this.autoLinkEnabled) { await this.createAutoLinks(entityName, text); } // Save changes await this.save(); return observation; }