list_passages
Retrieve paginated memories from an agent's archival store with search, sorting, and filtering capabilities.
Instructions
Retrieve the memories in an agent's archival memory store (paginated query). Use create_passage to add new memories, modify_passage to edit, or delete_passage to remove them.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| agent_id | Yes | ID of the agent whose passages to list | |
| after | No | Unique ID of the memory to start the query range at (for pagination). | |
| before | No | Unique ID of the memory to end the query range at (for pagination). | |
| limit | No | How many results to include in the response. | |
| search | No | Search passages by text content. | |
| order | No | Sort order for passages: "asc" for oldest to newest (default), "desc" for newest to oldest. (SDK v1.0) | asc |
| ascending | No | DEPRECATED: Use "order" instead. Whether to sort passages oldest to newest (True) or newest to oldest (False). | |
| include_embeddings | No | Whether to include the full embedding vectors in the response (default: false). |
Implementation Reference
- src/tools/passages/list-passages.js:4-61 (handler)Core handler function that executes the list_passages tool: validates args, constructs API query for agent's archival memory, fetches passages, optionally removes embeddings, and returns JSON stringified response.export async function handleListPassages(server, args) { if (!args?.agent_id) { server.createErrorResponse('Missing required argument: agent_id'); } try { const headers = server.getApiHeaders(); const agentId = encodeURIComponent(args.agent_id); // Construct query parameters based on optional args const params = {}; if (args.after) params.after = args.after; if (args.before) params.before = args.before; if (args.limit) params.limit = args.limit; if (args.search) params.search = args.search; // SDK v1.0: Use 'order' parameter instead of deprecated 'ascending' if (args.order) { params.order = args.order; // 'asc' or 'desc' } else if (args.ascending !== undefined) { // Backward compatibility: convert boolean ascending to order string params.order = args.ascending ? 'asc' : 'desc'; } // Use the specific endpoint from the OpenAPI spec const response = await server.api.get(`/agents/${agentId}/archival-memory`, { headers, params, }); let passages = response.data; // Assuming response.data is an array of Passage objects // Optionally remove embeddings from the response const includeEmbeddings = args?.include_embeddings ?? false; if (!includeEmbeddings) { passages = passages.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: passages, }), }, ], }; } catch (error) { // Handle potential 404 if agent not found, or other API errors if (error.response && error.response.status === 404) { server.createErrorResponse(`Agent not found: ${args.agent_id}`); } server.createErrorResponse(error); } }
- Tool definition object including name 'list_passages', description, and detailed inputSchema with properties for agent_id (required), pagination (after/before/limit), search, ordering, and optional embeddings inclusion.export const listPassagesDefinition = { name: 'list_passages', description: "Retrieve the memories in an agent's archival memory store (paginated query). Use create_passage to add new memories, modify_passage to edit, or delete_passage to remove them.", inputSchema: { type: 'object', properties: { agent_id: { type: 'string', description: 'ID of the agent whose passages to list', }, after: { type: 'string', description: 'Unique ID of the memory to start the query range at (for pagination).', }, before: { type: 'string', description: 'Unique ID of the memory to end the query range at (for pagination).', }, limit: { type: 'integer', description: 'How many results to include in the response.', }, search: { type: 'string', description: 'Search passages by text content.', }, order: { type: 'string', enum: ['asc', 'desc'], description: 'Sort order for passages: "asc" for oldest to newest (default), "desc" for newest to oldest. (SDK v1.0)', default: 'asc', }, ascending: { type: 'boolean', description: 'DEPRECATED: Use "order" instead. Whether to sort passages oldest to newest (True) or newest to oldest (False).', deprecated: true, }, include_embeddings: { type: 'boolean', description: 'Whether to include the full embedding vectors in the response (default: false).', default: false, }, }, required: ['agent_id'], }, };
- src/tools/index.js:43-43 (registration)Import statement bringing in the handler function and tool definition for use in central registration.import { handleListPassages, listPassagesDefinition } from './passages/list-passages.js';
- src/tools/index.js:193-194 (registration)Switch case in the central MCP tool call handler (registerToolHandlers) that dispatches calls to the list_passages handler.case 'list_passages': return handleListPassages(server, request.params.arguments);
- src/tools/index.js:124-124 (registration)Inclusion of listPassagesDefinition in the allTools array used for tool listing and enhanced registration.listPassagesDefinition,