create_passage
Store text memories in an agent's archival memory for later retrieval and management within the Letta system.
Instructions
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.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| agent_id | Yes | ID of the agent to add the passage to | |
| text | Yes | Text content to write to archival memory. | |
| include_embeddings | No | Whether to include the full embedding vectors in the response (default: false). |
Implementation Reference
- 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); } }
- 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';