add_observations

Add observations to entities in a knowledge graph memory system to enhance entity data with details like content, strength, confidence, and metadata.

Instructions

Add new observations to existing entities in your Memento MCP knowledge graph memory

Input Schema

TableJSON Schema

Name	Required	Description
`observations`	Yes
`strength`	No	Default strength value (0.0 to 1.0) for all observations
`confidence`	No	Default confidence level (0.0 to 1.0) for all observations
`metadata`	No	Default metadata for all observations

Implementation Reference

src/server/handlers/toolHandlers/addObservations.ts:8-127 (handler)

The primary handler function for the 'add_observations' tool. Validates input arguments, processes observations with defaults for strength and confidence, and delegates to knowledgeGraphManager.addObservations.

export async function handleAddObservations(
  args: Record<string, unknown>,
  // eslint-disable-next-line @typescript-eslint/no-explicit-any
  knowledgeGraphManager: any
): Promise<{ content: Array<{ type: string; text: string }> }> {
  try {
    // Enhanced logging for debugging
    process.stderr.write(`[DEBUG] addObservations handler called at ${new Date().toISOString()}\n`);
    process.stderr.write(`[DEBUG] FULL ARGS: ${JSON.stringify(args, null, 2)}\n`);
    process.stderr.write(`[DEBUG] ARGS KEYS: ${Object.keys(args).join(', ')}\n`);
    process.stderr.write(
      `[DEBUG] ARGS TYPES: ${Object.keys(args)
        .map((k) => `${k}: ${typeof args[k]}`)
        .join(', ')}\n`
    );

    // Validate the observations array
    if (!args.observations || !Array.isArray(args.observations)) {
      throw new Error('Invalid observations: must be an array');
    }

    // Add default values for required parameters
    const defaultStrength = 0.9;
    const defaultConfidence = 0.95;

    // Force add strength to args if it doesn't exist
    if (args.strength === undefined) {
      process.stderr.write(`[DEBUG] Adding default strength value: ${defaultStrength}\n`);
      args.strength = defaultStrength;
    }

    // Ensure each observation has the required fields
    // eslint-disable-next-line @typescript-eslint/no-explicit-any
    const processedObservations = args.observations.map((obs: any) => {
      // Validate required fields
      if (!obs.entityName) {
        throw new Error('Missing required parameter: entityName');
      }
      if (!obs.contents || !Array.isArray(obs.contents)) {
        throw new Error('Missing required parameter: contents (must be an array)');
      }

      // Always set strength value
      const obsStrength = obs.strength !== undefined ? obs.strength : args.strength;

      process.stderr.write(
        `[DEBUG] Processing observation for ${obs.entityName}, using strength: ${obsStrength}\n`
      );

      // Set defaults for each observation
      return {
        entityName: obs.entityName,
        contents: obs.contents,
        strength: obsStrength,
        confidence:
          obs.confidence !== undefined ? obs.confidence : args.confidence || defaultConfidence,
        metadata: obs.metadata || args.metadata || { source: 'API call' },
      };
    });

    // Call knowledgeGraphManager
    process.stderr.write(
      `[DEBUG] Calling knowledgeGraphManager.addObservations with ${processedObservations.length} observations\n`
    );
    process.stderr.write(`[DEBUG] PROCESSED: ${JSON.stringify(processedObservations, null, 2)}\n`);

    const result = await knowledgeGraphManager.addObservations(processedObservations);

    process.stderr.write(`[DEBUG] addObservations result: ${JSON.stringify(result, null, 2)}\n`);

    return {
      content: [
        {
          type: 'text',
          text: JSON.stringify(
            {
              result,
              debug: {
                timestamp: Date.now(),
                input_args: args,
                processed_observations: processedObservations,
                tool_version: 'v2 with debug info',
              },
            },
            null,
            2
          ),
        },
      ],
    };
  } catch (error) {
    // eslint-disable-next-line @typescript-eslint/no-explicit-any
    const err = error as any;
    // Enhanced error logging for debugging
    process.stderr.write(`[ERROR] addObservations error: ${err.message}\n`);
    process.stderr.write(`[ERROR] Stack trace: ${err.stack || 'No stack trace available'}\n`);

    return {
      content: [
        {
          type: 'text',
          text: JSON.stringify(
            {
              error: err.message,
              debug: {
                timestamp: Date.now(),
                input_args: args || 'No args available',
                error_type: err.constructor.name,
                error_stack: err.stack?.split('\n') || 'No stack trace',
                tool_version: 'v2 with debug info',
              },
            },
            null,
            2
          ),
        },
      ],
    };
  }
}

src/server/handlers/listToolsHandler.ts:105-159 (schema)

JSON schema definition for the 'add_observations' tool, specifying input structure for observations array with entityName, contents, and optional parameters.

name: 'add_observations',
description:
  'Add new observations to existing entities in your Memento MCP knowledge graph memory',
inputSchema: {
  type: 'object',
  properties: {
    observations: {
      type: 'array',
      items: {
        type: 'object',
        properties: {
          entityName: {
            type: 'string',
            description: 'The name of the entity to add the observations to',
          },
          contents: {
            type: 'array',
            items: { type: 'string' },
            description: 'An array of observation contents to add',
          },
          // Optional parameters at the observation level
          strength: {
            type: 'number',
            description: 'Strength value (0.0 to 1.0) for this specific observation',
          },
          confidence: {
            type: 'number',
            description: 'Confidence level (0.0 to 1.0) for this specific observation',
          },
          metadata: {
            type: 'object',
            description: 'Metadata for this specific observation',
            additionalProperties: true,
          },
        },
        required: ['entityName', 'contents'],
      },
    },
    // Optional parameters at the top level (apply to all observations)
    strength: {
      type: 'number',
      description: 'Default strength value (0.0 to 1.0) for all observations',
    },
    confidence: {
      type: 'number',
      description: 'Default confidence level (0.0 to 1.0) for all observations',
    },
    metadata: {
      type: 'object',
      description: 'Default metadata for all observations',
      additionalProperties: true,
    },
  },
  required: ['observations'],
},

src/server/handlers/callToolHandler.ts:47-48 (registration)
Dispatch logic in the main CallTool handler that routes 'add_observations' calls to the specific tool handler.
```
case 'add_observations':
  return await toolHandlers.handleAddObservations(args, knowledgeGraphManager);
```
src/server/handlers/toolHandlers/index.ts:7-7 (registration)
Re-exports the handleAddObservations function from its module for centralized import in callToolHandler.
```
export { handleAddObservations } from './addObservations.js';
```

memento-mcp