create_memory_block

Create structured memory blocks with labels like persona, human, or system for organizing information in the Letta system. Link blocks to agents or update content as needed.

Instructions

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.

Input Schema

TableJSON Schema

Name	Required	Description
`name`	Yes	Name of the memory block
`label`	Yes	Label for the memory block (e.g., "persona", "human", "system")
`value`	Yes	Content of the memory block
`agent_id`	No	Optional agent ID to create the block for a specific agent
`metadata`	No	Optional metadata for the memory block

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'],
},

Letta MCP Server