Letta MCP Server

Instructions

Implementation Reference

• src/tools/messages/create-conversation-entry.js:8-78 (handler)

  The main handler function that executes the tool logic: validates args, formats the conversation entry as JSON matching Letta's message structure, posts it to the agent's archival memory, and returns success response with passage ID.

  export async function handleCreateConversationEntry(server, args) {
      if (!args?.agent_id) {
          throw new Error('Missing required argument: agent_id');
      }
      if (!args?.role) {
          throw new Error('Missing required argument: role');
      }
      if (!args?.content) {
          throw new Error('Missing required argument: content');
      }
  
      try {
          const headers = server.getApiHeaders();
          const agentId = encodeURIComponent(args.agent_id);
  
          // Format the conversation entry to match Letta's message structure
          const timestamp = args.timestamp || new Date().toISOString();
          const source = args.source || 'unknown';
          const sessionId = args.session_id || 'no-session';
  
          // Map role to Letta message_type
          const messageTypeMap = {
              user: 'user_message',
              assistant: 'assistant_message',
              system: 'system_message',
          };
  
          // Create JSON structure matching Letta message format
          const messageEntry = {
              message_type: messageTypeMap[args.role] || 'user_message',
              date: timestamp,
              role: args.role,
              text: args.content,
              source: source,
              session_id: sessionId,
          };
  
          // Store as JSON for consistent parsing and search
          const entryText = JSON.stringify(messageEntry);
  
          // Create the passage
          const response = await server.api.post(
              `/agents/${agentId}/archival-memory`,
              { text: entryText },
              { headers },
          );
  
          // Strip embeddings from response
          const passage = response.data;
          if (passage.embedding) {
              delete passage.embedding;
          }
  
          return {
              content: [
                  {
                      type: 'text',
                      text: JSON.stringify({
                          success: true,
                          passage_id: passage.id,
                          timestamp: timestamp,
                          role: args.role,
                          source: source,
                      }),
                  },
              ],
          };
      } catch (error) {
          return server.createErrorResponse(error);
      }
  }

• src/tools/messages/create-conversation-entry.js:83-119 (schema)

  The tool definition object including name, description, and detailed inputSchema for parameter validation with types, enums, descriptions, and required fields.

  export const createConversationEntryDefinition = {
      name: 'create_conversation_entry',
      description:
          "Store a conversation entry in an agent's archival memory. Use this to record conversations from external sources (like Claude Code sessions) that should be searchable via search_archival_memory. Entries are formatted with metadata for easy filtering.",
      inputSchema: {
          type: 'object',
          properties: {
              agent_id: {
                  type: 'string',
                  description: 'ID of the agent to store the conversation entry for',
              },
              role: {
                  type: 'string',
                  enum: ['user', 'assistant', 'system'],
                  description: 'Role of the message sender',
              },
              content: {
                  type: 'string',
                  description: 'The message content',
              },
              timestamp: {
                  type: 'string',
                  format: 'date-time',
                  description: 'ISO 8601 timestamp of the message (defaults to now)',
              },
              source: {
                  type: 'string',
                  description: 'Source of the conversation (e.g., "claude_code", "letta_ade")',
              },
              session_id: {
                  type: 'string',
                  description: 'Session identifier for grouping related messages',
              },
          },
          required: ['agent_id', 'role', 'content'],
      },
  };

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

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

  import {
      handleCreateConversationEntry,
      createConversationEntryDefinition,
  } from './messages/create-conversation-entry.js';

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

  Inclusion of the tool definition in the allTools array used for registration with the MCP server.

      listMessagesDefinition,
      createConversationEntryDefinition,
  ];

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

  Switch case in the tool call handler that dispatches calls to 'create_conversation_entry' to the specific handler function.

  case 'create_conversation_entry':
      return handleCreateConversationEntry(server, request.params.arguments);