create_conversation_entry
Store conversation entries in an agent's archival memory for searchable records from external sources like Claude Code sessions, using metadata for filtering.
Instructions
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.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| agent_id | Yes | ID of the agent to store the conversation entry for | |
| role | Yes | Role of the message sender | |
| content | Yes | The message content | |
| timestamp | No | ISO 8601 timestamp of the message (defaults to now) | |
| source | No | Source of the conversation (e.g., "claude_code", "letta_ade") | |
| session_id | No | Session identifier for grouping related messages |
Implementation Reference
- 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); } }
- 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);