mcp-structured-memory

Instructions

Implementation Reference

• src/tools/listMemories.ts:3-51 (handler)

  The handler function that implements the core logic of the list_memories tool: fetches memories from storage manager, handles empty case with instructions, formats a detailed markdown list of memories with metadata, and returns in MCP content format.

  export async function listMemoriesTool(
    storageManager: StorageManager,
    _args: any
  ): Promise<any> {
    const memories = await storageManager.listMemories();
  
    if (memories.length === 0) {
      return {
        content: [{
          type: 'text',
          text: `No memory documents found.
  
  To create your first memory document, use the create_memory tool with any name and optional context:
  
  Examples:
  - "Create a memory document called 'minnesota trip 2025'"
  - "Create a memory document for 'my travel plans' with context about exploring the North Shore and Twin Cities"
  - "Create a memory document called 'midwest adventure' with context about visiting state parks and local attractions"`
        }]
      };
    }
  
    let result = `Found ${memories.length} memory document${memories.length === 1 ? '' : 's'}:\n\n`;
  
    for (const memory of memories) {
      const statusText = memory.status ? ` (${memory.status})` : '';
      
      result += `## ${memory.id}${statusText}\n`;
      result += `- **Created**: ${memory.created.split('T')[0]}\n`;
      result += `- **Updated**: ${memory.updated.split('T')[0]}\n`;
      result += `- **Sections**: ${memory.sectionCount}\n`;
      
      if (memory.tags.length > 0) {
        result += `- **Tags**: ${memory.tags.join(', ')}\n`;
      }
      
      result += `- **File**: ${memory.filePath}\n\n`;
    }
  
    result += `---
  *Use get_section to read specific sections, or add_to_list to add items to any memory document.*`;
  
    return {
      content: [{
        type: 'text',
        text: result
      }]
    };
  }

• src/index.ts:100-108 (registration)

  Registration of the list_memories tool in the MCP server's listTools handler, defining its name, description, and empty input schema (no parameters required).

  {
    name: "list_memories",
    description: "List all available memory documents",
    inputSchema: {
      type: "object",
      properties: {},
      additionalProperties: false,
    },
  },

• src/index.ts:268-269 (registration)

  Dispatch/execution routing for the list_memories tool in the CallToolRequestHandler switch statement, calling the listMemoriesTool handler.

  case "list_memories":
    return await listMemoriesTool(storageManager, args);

• src/storage/StorageManager.ts:130-166 (helper)

  Core helper method in StorageManager that scans the storage directory for .md files, parses frontmatter to extract metadata, counts sections, and returns sorted list of MemorySummary objects.

  async listMemories(): Promise<MemorySummary[]> {
    await this.ensureStorageDirectory();
  
    try {
      const files = await fs.readdir(this.storagePath);
      const memoryFiles = files.filter(
        (file) => file.endsWith(".md") && !file.startsWith(".")
      );
  
      const summaries: MemorySummary[] = [];
  
      for (const file of memoryFiles) {
        const filePath = path.join(this.storagePath, file);
        const content = await fs.readFile(filePath, "utf-8");
        const parsed = matter(content);
        const memoryId = path.basename(file, ".md");
  
        const sections = this.parseSections(parsed.content);
  
        summaries.push({
          id: parsed.data.id || memoryId,
          created: parsed.data.created || new Date().toISOString(),
          updated: parsed.data.updated || new Date().toISOString(),
          tags: parsed.data.tags || [],
          status: parsed.data.status,
          filePath,
          sectionCount: sections.length,
        });
      }
  
      return summaries.sort(
        (a, b) => new Date(b.updated).getTime() - new Date(a.updated).getTime()
      );
    } catch (_error) {
      return [];
    }
  }