Letta MCP Server

Instructions

Implementation Reference

• src/tools/passages/create-passage.js:4-57 (handler)

  The handler function that implements the core logic of the 'create_passage' tool, validating inputs, making an API POST request to create passages in the agent's archival memory, processing the response (optionally stripping embeddings), and returning the result.

  export async function handleCreatePassage(server, args) {
      if (!args?.agent_id) {
          server.createErrorResponse('Missing required argument: agent_id');
      }
      if (args?.text === undefined || args?.text === null) {
          server.createErrorResponse('Missing required argument: text');
      }
  
      try {
          const headers = server.getApiHeaders();
          const agentId = encodeURIComponent(args.agent_id);
          const payload = { text: args.text }; // Body requires 'text'
  
          // Use the specific endpoint from the OpenAPI spec
          const response = await server.api.post(`/agents/${agentId}/archival-memory`, payload, {
              headers,
          });
          let createdPassages = response.data; // Assuming response.data is an array of created Passage objects
  
          // Optionally remove embeddings from the response
          const includeEmbeddings = args?.include_embeddings ?? false;
          if (!includeEmbeddings) {
              createdPassages = createdPassages.map((passage) => {
                  // eslint-disable-next-line no-unused-vars
                  const { embedding, ...rest } = passage; // Destructure to remove embedding
                  return rest;
              });
          }
  
          return {
              content: [
                  {
                      type: 'text',
                      text: JSON.stringify({
                          passages: createdPassages,
                      }),
                  },
              ],
          };
      } catch (error) {
          // Handle potential 404 if agent not found, 422 for validation, or other API errors
          if (error.response) {
              if (error.response.status === 404) {
                  server.createErrorResponse(`Agent not found: ${args.agent_id}`);
              }
              if (error.response.status === 422) {
                  server.createErrorResponse(
                      `Validation error creating passage for agent ${args.agent_id}: ${JSON.stringify(error.response.data)}`,
                  );
              }
          }
          server.createErrorResponse(error);
      }
  }

• src/tools/passages/create-passage.js:62-86 (schema)

  The tool definition including name, description, and input schema for 'create_passage', specifying required parameters (agent_id, text) and optional include_embeddings.

  export const createPassageDefinition = {
      name: 'create_passage',
      description:
          "Insert a memory into an agent's archival memory store. Use list_passages to view existing memories, modify_passage to edit, or delete_passage to remove.",
      inputSchema: {
          type: 'object',
          properties: {
              agent_id: {
                  type: 'string',
                  description: 'ID of the agent to add the passage to',
              },
              text: {
                  type: 'string',
                  description: 'Text content to write to archival memory.',
              },
              include_embeddings: {
                  type: 'boolean',
                  description:
                      'Whether to include the full embedding vectors in the response (default: false).',
                  default: false,
              },
          },
          required: ['agent_id', 'text'],
      },
  };

• src/tools/index.js:195-196 (registration)

  Registration of the 'create_passage' tool handler in the main tool dispatch switch statement within registerToolHandlers.

  case 'create_passage':
      return handleCreatePassage(server, request.params.arguments);

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

  Inclusion of createPassageDefinition in the allTools array for tool list registration.

  createPassageDefinition,

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

  Import of the handler and definition from the implementation file.

  import { handleCreatePassage, createPassageDefinition } from './passages/create-passage.js';