Letta MCP Server

Instructions

Implementation Reference

• src/tools/memory/create-memory-block.js:8-90 (handler)

  Main handler function for 'create_memory_block' tool. Validates input args (name, label, value), creates memory block via POST /blocks API, optionally attaches to agent if agent_id provided, returns structured content with block_id and details.

  export async function handleCreateMemoryBlock(server, args) {
      try {
          // Validate arguments
          if (!args.name || typeof args.name !== 'string') {
              throw new Error('Missing required argument: name (must be a string)');
          }
          if (!args.label || typeof args.label !== 'string') {
              throw new Error('Missing required argument: label (must be a string)');
          }
          if (!args.value || typeof args.value !== 'string') {
              throw new Error('Missing required argument: value (must be a string)');
          }
  
          // Headers for API requests
          const headers = server.getApiHeaders();
  
          // If agent_id is provided, set the user_id header
          if (args.agent_id) {
              headers['user_id'] = args.agent_id;
          }
  
          // Prepare metadata
          const metadata = args.metadata || {
              type: args.label,
              version: '1.0',
              last_updated: new Date().toISOString(),
          };
  
          // Prepare block data
          const blockData = {
              name: args.name,
              label: args.label,
              value: args.value,
              metadata: metadata,
          };
  
          // Create the memory block
          logger.info(`Creating memory block "${args.name}" with label "${args.label}"...`);
          const createResponse = await server.api.post('/blocks', blockData, { headers });
          const blockId = createResponse.data.id;
  
          // If agent_id is provided, attach the block to the agent
          if (args.agent_id) {
              const attachUrl = `/agents/${args.agent_id}/core-memory/blocks/attach/${blockId}`;
              await server.api.patch(attachUrl, {}, { headers });
  
              // Get agent info
              const agentInfoResponse = await server.api.get(`/agents/${args.agent_id}`, { headers });
              const agentName = agentInfoResponse.data.name || 'Unknown';
  
              return {
                  content: [
                      {
                          type: 'text',
                          text: JSON.stringify({
                              block_id: blockId,
                              name: args.name,
                              label: args.label,
                              agent_id: args.agent_id,
                              agent_name: agentName,
                          }),
                      },
                  ],
              };
          } else {
              // Just return the created block info
              return {
                  content: [
                      {
                          type: 'text',
                          text: JSON.stringify({
                              block_id: blockId,
                              name: args.name,
                              label: args.label,
                          }),
                      },
                  ],
              };
          }
      } catch (error) {
          server.createErrorResponse(error);
      }
  }

• src/tools/memory/create-memory-block.js:95-125 (schema)

  Tool definition object with name, description, and inputSchema defining required parameters (name, label, value) and optional (agent_id, metadata).

  export const createMemoryBlockToolDefinition = {
      name: 'create_memory_block',
      description:
          'Create a new memory block in the Letta system. Common labels: "persona", "human", "system". Use attach_memory_block to link to agents, or update_memory_block to modify later.',
      inputSchema: {
          type: 'object',
          properties: {
              name: {
                  type: 'string',
                  description: 'Name of the memory block',
              },
              label: {
                  type: 'string',
                  description: 'Label for the memory block (e.g., "persona", "human", "system")',
              },
              value: {
                  type: 'string',
                  description: 'Content of the memory block',
              },
              agent_id: {
                  type: 'string',
                  description: 'Optional agent ID to create the block for a specific agent',
              },
              metadata: {
                  type: 'object',
                  description: 'Optional metadata for the memory block',
              },
          },
          required: ['name', 'label', 'value'],
      },
  };

• src/tools/index.js:33-35 (registration)

  Import of the handler function and tool definition from the implementation file.

      handleCreateMemoryBlock,
      createMemoryBlockToolDefinition,
  } from './memory/create-memory-block.js';

• src/tools/index.js:171-172 (registration)

  Registration/dispatch of the 'create_memory_block' tool call to the specific handler in the central switch statement within registerToolHandlers.

  case 'create_memory_block':
      return handleCreateMemoryBlock(server, request.params.arguments);

• src/tools/output-schemas.js:114-124 (schema)

  Output schema for 'create_memory_block' tool responses, defining expected structure (id, name, label, etc.) for structured outputs.

  create_memory_block: {
      type: 'object',
      properties: {
          id: { type: 'string', description: 'Unique identifier of the created memory block' },
          name: { type: 'string' },
          label: { type: 'string' },
          value: { type: 'string' },
          metadata: { type: 'object' },
      },
      required: ['id', 'name', 'label'],
  },