mcp-structured-memory

Instructions

Implementation Reference

• src/tools/getMemorySummary.ts:31-105 (handler)

  Main handler function for the get_memory_summary tool. Reads the memory document, parses sections, computes statistics (sections, words, list items, active sections, age), generates formatted summary text using helpers, and returns it as MCP content.

  export async function getMemorySummaryTool(
    storageManager: StorageManager,
    args: any
  ): Promise<any> {
    const params = args as GetMemorySummaryParams;
    
    if (!params.memory_id) {
      throw new Error('memory_id is required');
    }
  
    // Read the memory document
    const memory = await storageManager.readMemory(params.memory_id);
    if (!memory) {
      throw new Error(`Memory document '${params.memory_id}' not found`);
    }
  
    // Parse sections for analysis
    const sections = storageManager.parseSections(memory.content);
    
    // Generate summary statistics
    const totalSections = sections.length;
    const nonEmptySections = sections.filter(s => s.content.trim().length > 0).length;
    
    // Count different types of content
    let totalItems = 0;
    let listSections = 0;
    
    sections.forEach(section => {
      const content = section.content.trim();
      if (content) {
        const analysis = analyzeContent(content);
        if (analysis.totalItems > 0) {
          totalItems += analysis.totalItems;
          listSections++;
        }
      }
    });
  
    // Calculate content metrics
    const totalWords = memory.content.split(/\s+/).filter(word => word.length > 0).length;
    const totalChars = memory.content.length;
    
    // Identify the most active sections (by content length)
    const activeSections = findActiveSections(sections);
  
    // Format creation and update dates
    const created = new Date(memory.metadata.created);
    const updated = new Date(memory.metadata.updated);
    const daysSinceCreated = calculateDaysSince(created.getTime());
    const daysSinceUpdated = calculateDaysSince(updated.getTime());
  
    // Build summary using helper function
    const summaryData: SummaryData = {
      memory,
      totalSections,
      nonEmptySections,
      listSections,
      totalItems,
      totalWords,
      totalChars,
      activeSections,
      daysSinceCreated,
      daysSinceUpdated,
      sections
    };
    
    const summary = generateSummaryText(summaryData);
  
    return {
      content: [{
        type: 'text',
        text: summary
      }]
    };
  }

• src/types/memory.ts:52-54 (schema)

  TypeScript interface defining the input parameters for the get_memory_summary tool (requires memory_id).

  export interface GetMemorySummaryParams {
    memory_id: string;
  }

• src/index.ts:109-122 (registration)

  Tool registration in the ListTools handler, specifying name, description, and input schema for MCP protocol compliance.

  {
    name: "get_memory_summary",
    description: "Get a high-level summary of a memory document",
    inputSchema: {
      type: "object",
      properties: {
        memory_id: {
          type: "string",
          description: "The ID of the memory document to summarize",
        },
      },
      required: ["memory_id"],
    },
  },

• src/index.ts:271-272 (registration)

  Dispatch in the CallTool handler switch statement, invoking the tool implementation.

  case "get_memory_summary":
    return await getMemorySummaryTool(storageManager, args);

• src/tools/getMemorySummary.ts:6-29 (helper)

  Helper functions used by the handler: analyzeContent for list/heading detection, calculateDaysSince for age computation, findActiveSections for top sections by length.

  export function analyzeContent(content: string): { bulletCount: number; numberedCount: number; headingCount: number; totalItems: number } {
    const bulletMatches = content.match(/^[\s]*[-*+]\s/gm) || [];
    const numberedMatches = content.match(/^[\s]*\d+\.\s/gm) || [];
    const headingMatches = content.match(/^[\s]*#{3,}\s/gm) || [];
    
    return {
      bulletCount: bulletMatches.length,
      numberedCount: numberedMatches.length,
      headingCount: headingMatches.length,
      totalItems: bulletMatches.length + numberedMatches.length + headingMatches.length
    };
  }
  
  export function calculateDaysSince(timestamp: number): number {
    return Math.floor((Date.now() - timestamp) / (1000 * 60 * 60 * 24));
  }
  
  export function findActiveSections(sections: Array<{ name: string; content: string }>): string[] {
    return sections
      .filter(s => s.content.trim().length > 0)
      .sort((a, b) => b.content.length - a.content.length)
      .slice(0, 3)
      .map(s => s.name);
  }