list_memories
Organize and explore stored knowledge by filtering memories by category and retrieving insights. Ideal for reviewing accumulated information, identifying patterns, and maintaining decision awareness.
Instructions
Browse and explore your knowledge repository with organized memory listings and flexible category filtering. Perfect for reviewing stored information, discovering patterns in your knowledge base, and maintaining awareness of your accumulated insights and decisions.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| category | No | Filter to memories in this specific category | |
| limit | No | Maximum number of memories to return (default: 50) | |
| workingDirectory | Yes | The full absolute path to the working directory where data is stored. MUST be an absolute path, never relative. Windows: "C:\Users\username\project" or "D:\projects\my-app". Unix/Linux/macOS: "/home/username/project" or "/Users/username/project". Do NOT use: ".", "..", "~", "./folder", "../folder" or any relative paths. Ensure the path exists and is accessible before calling this tool. NOTE: When server is started with --claude flag, this parameter is ignored and a global user directory is used instead. |
Implementation Reference
- src/server.ts:813-840 (registration)MCP server.tool() registration for 'list_memories'. Creates MemoryStorage instance and invokes createListMemoriesTool(storage).handler with parameters.
server.tool( 'list_memories', 'Browse and explore your knowledge repository with organized memory listings and flexible category filtering. Perfect for reviewing stored information, discovering patterns in your knowledge base, and maintaining awareness of your accumulated insights and decisions.', { workingDirectory: z.string().describe(getWorkingDirectoryDescription(config)), category: z.string().optional().describe('Filter to memories in this specific category'), limit: z.number().min(1).max(1000).optional().describe('Maximum number of memories to return (default: 50)') }, async ({ workingDirectory, category, limit }: { workingDirectory: string; category?: string; limit?: number; }) => { try { const storage = await createMemoryStorage(workingDirectory, config); const tool = createListMemoriesTool(storage); return await tool.handler({ category, limit }); } catch (error) { return { content: [{ type: 'text' as const, text: `Error: ${error instanceof Error ? error.message : 'Unknown error'}` }], isError: true }; } } ); - Core handler function for list_memories tool. Validates inputs, fetches memories from storage with optional category/limit filters, sorts by newest first, formats list with previews and stats, handles empty results and errors.
handler: async ({ category, limit = 50 }: { category?: string; limit?: number; }) => { try { // Validate inputs if (limit < 1 || limit > 1000) { return { content: [{ type: 'text' as const, text: 'Error: Limit must be between 1 and 1000.' }], isError: true }; } if (category && category.trim().length > 100) { return { content: [{ type: 'text' as const, text: 'Error: Category must be 100 characters or less.' }], isError: true }; } const memories = await storage.getMemories( undefined, // agentId removed category?.trim(), limit ); if (memories.length === 0) { return { content: [{ type: 'text' as const, text: `📝 No memories found. **Filters:** ${[ category && `Category: ${category}` ].filter(Boolean).join(', ') || 'None'} Create some memories using the create_memory tool to get started!` }] }; } // Sort memories by creation date (newest first) const sortedMemories = memories.sort((a, b) => new Date(b.createdAt).getTime() - new Date(a.createdAt).getTime() ); const memoryList = sortedMemories.map((memory, index) => { return `**${index + 1}. ${memory.title}** Content: ${memory.content.substring(0, 150)}${memory.content.length > 150 ? '...' : ''} Category: ${memory.category || 'Not specified'} Created: ${new Date(memory.createdAt).toLocaleString()}`; }).join('\n\n'); // Get statistics const stats = await storage.getStatistics(); return { content: [{ type: 'text' as const, text: `📝 Found ${memories.length} memory(ies): **Filters:** ${[ category && `Category: ${category}` ].filter(Boolean).join(', ') || 'None'} **Limit:** ${limit} ${memoryList} --- **📊 Overall Statistics:** • Total memories: ${stats.totalMemories} • Categories: ${Object.keys(stats.memoriesByCategory).length} • Oldest memory: ${stats.oldestMemory ? new Date(stats.oldestMemory).toLocaleString() : 'None'} • Newest memory: ${stats.newestMemory ? new Date(stats.newestMemory).toLocaleString() : 'None'} Use get_memory with a specific ID to see full details, or search_memories for text-based search.` }] }; } catch (error) { return { content: [{ type: 'text' as const, text: `Error listing memories: ${error instanceof Error ? error.message : 'Unknown error'}` }], isError: true }; } } - Zod input schema definition for the list_memories tool: optional category (string), optional limit (number 1-1000).
inputSchema: { category: z.string().optional(), limit: z.number().min(1).max(1000).optional() }, - src/features/agent-memories/tools/memories/list.ts:10-117 (registration)Factory function createListMemoriesTool that returns the complete tool object specification including name, description, inputSchema, and handler for registration.
export function createListMemoriesTool(storage: MemoryStorage) { return { name: 'list_memories', description: 'List memories with optional filtering by category and limit', inputSchema: { category: z.string().optional(), limit: z.number().min(1).max(1000).optional() }, handler: async ({ category, limit = 50 }: { category?: string; limit?: number; }) => { try { // Validate inputs if (limit < 1 || limit > 1000) { return { content: [{ type: 'text' as const, text: 'Error: Limit must be between 1 and 1000.' }], isError: true }; } if (category && category.trim().length > 100) { return { content: [{ type: 'text' as const, text: 'Error: Category must be 100 characters or less.' }], isError: true }; } const memories = await storage.getMemories( undefined, // agentId removed category?.trim(), limit ); if (memories.length === 0) { return { content: [{ type: 'text' as const, text: `📝 No memories found. **Filters:** ${[ category && `Category: ${category}` ].filter(Boolean).join(', ') || 'None'} Create some memories using the create_memory tool to get started!` }] }; } // Sort memories by creation date (newest first) const sortedMemories = memories.sort((a, b) => new Date(b.createdAt).getTime() - new Date(a.createdAt).getTime() ); const memoryList = sortedMemories.map((memory, index) => { return `**${index + 1}. ${memory.title}** Content: ${memory.content.substring(0, 150)}${memory.content.length > 150 ? '...' : ''} Category: ${memory.category || 'Not specified'} Created: ${new Date(memory.createdAt).toLocaleString()}`; }).join('\n\n'); // Get statistics const stats = await storage.getStatistics(); return { content: [{ type: 'text' as const, text: `📝 Found ${memories.length} memory(ies): **Filters:** ${[ category && `Category: ${category}` ].filter(Boolean).join(', ') || 'None'} **Limit:** ${limit} ${memoryList} --- **📊 Overall Statistics:** • Total memories: ${stats.totalMemories} • Categories: ${Object.keys(stats.memoriesByCategory).length} • Oldest memory: ${stats.oldestMemory ? new Date(stats.oldestMemory).toLocaleString() : 'None'} • Newest memory: ${stats.newestMemory ? new Date(stats.newestMemory).toLocaleString() : 'None'} Use get_memory with a specific ID to see full details, or search_memories for text-based search.` }] }; } catch (error) { return { content: [{ type: 'text' as const, text: `Error listing memories: ${error instanceof Error ? error.message : 'Unknown error'}` }], isError: true }; } } }; }