memory_summary

Instructions

Implementation Reference

• src/index.ts:301-332 (handler)

  The tool handler for 'memory_summary'. Calls store.stats() and returns a formatted summary including total memory count, average importance, storage file, top tags, most important memories (top 5), and most accessed memories (top 3). If no memories exist, returns an empty state message.

  case 'memory_summary': {
    const stats = store.stats();
  
    if (stats.total === 0) {
      return ok(`Memory Hub is empty.\nStorage location: ${stats.storageFile}\n\nNo memories stored yet. Use store_memory to begin.`);
    }
  
    const topImportant = [...store.all()]
      .sort((a, b) => b.importance - a.importance)
      .slice(0, 5)
      .map(m => `  • [${m.key}] (${m.importance}/10)  ${m.content.slice(0, 80)}${m.content.length > 80 ? '…' : ''}`)
      .join('\n');
  
    const tagList = stats.topTags.length
      ? stats.topTags.map(t => `  ${t.tag}: ${t.count}`).join('\n')
      : '  (none)';
  
    const accessList = stats.mostAccessed.length
      ? stats.mostAccessed.map(m => `  ${m.key} (${m.accessCount}×)`).join('\n')
      : '  (none)';
  
    return ok(
      `Memory Hub Summary\n` +
      `${'─'.repeat(40)}\n` +
      `Total memories:   ${stats.total}\n` +
      `Avg importance:   ${stats.avgImportance}/10\n` +
      `Storage:          ${stats.storageFile}\n` +
      `\nTop tags:\n${tagList}\n` +
      `\nMost important:\n${topImportant}\n` +
      `\nMost accessed:\n${accessList}`
    );
  }

• src/index.ts:139-148 (schema)

  The tool registration with input schema for 'memory_summary'. It has no required parameters (empty properties object), and provides a description: 'Get a high-level overview of what the agent knows — total count, top tags, most important memories, and access statistics.'

  {
    name: 'memory_summary',
    description:
      'Get a high-level overview of what the agent knows — total count, top tags, ' +
      'most important memories, and access statistics. Good for orientation at session start.',
    inputSchema: {
      type: 'object',
      properties: {},
    },
  },

• src/index.ts:23-150 (registration)

  The tool is registered within the ListToolsRequestSchema handler (line 23-150) as part of the tools array returned to the MCP client.

  server.setRequestHandler(ListToolsRequestSchema, async () => ({
    tools: [
      {
        name: 'store_memory',
        description:
          'Store a new memory — fact, preference, project detail, note, or any information worth remembering. ' +
          'Tags and importance are auto-detected from content if not provided.',
        inputSchema: {
          type: 'object',
          properties: {
            key: {
              type: 'string',
              description: 'Unique snake_case identifier (e.g. "user_name", "preferred_language", "project_deadline")',
            },
            content: {
              type: 'string',
              description: 'The memory content — be descriptive and specific for better retrieval',
            },
            tags: {
              type: 'array',
              items: { type: 'string' },
              description: 'Categorization tags (auto-detected if omitted)',
            },
            importance: {
              type: 'number',
              description: 'Importance score 1-10 — higher = retrieved first (auto-scored if omitted)',
            },
          },
          required: ['key', 'content'],
        },
      },
      {
        name: 'search_memory',
        description:
          'Search memories using BM25 full-text search with importance and recency weighting. ' +
          'Supports optional tag filtering to narrow scope.',
        inputSchema: {
          type: 'object',
          properties: {
            query: { type: 'string', description: 'Search query — natural language or keywords' },
            limit: { type: 'number', description: 'Max results to return (default: 5)' },
            tags: {
              type: 'array',
              items: { type: 'string' },
              description: 'Only search memories with these tags',
            },
          },
          required: ['query'],
        },
      },
      {
        name: 'get_relevant_context',
        description:
          'Auto-retrieve the most relevant memories for a given user query or task. ' +
          'Use this at the start of any session or when the user references past context. ' +
          'Returns formatted context ready to inject into your reasoning.',
        inputSchema: {
          type: 'object',
          properties: {
            user_query: {
              type: 'string',
              description: 'The current user query, task description, or topic to find context for',
            },
          },
          required: ['user_query'],
        },
      },
      {
        name: 'update_memory',
        description: 'Update the content, tags, or importance of an existing memory by key.',
        inputSchema: {
          type: 'object',
          properties: {
            key: { type: 'string', description: 'The memory key to update' },
            new_content: { type: 'string', description: 'Replacement content (omit to keep existing)' },
            tags: {
              type: 'array',
              items: { type: 'string' },
              description: 'New tag list — replaces existing tags',
            },
            importance: { type: 'number', description: 'New importance score 1-10' },
          },
          required: ['key'],
        },
      },
      {
        name: 'list_memories',
        description: 'Browse stored memories with optional tag filtering and sort order.',
        inputSchema: {
          type: 'object',
          properties: {
            tags: {
              type: 'array',
              items: { type: 'string' },
              description: 'Filter to only memories with these tags',
            },
            limit: { type: 'number', description: 'Max results (default: 20)' },
            sort: {
              type: 'string',
              enum: ['recent', 'importance', 'access'],
              description: 'Sort by: recent (default), importance, or access count',
            },
          },
        },
      },
      {
        name: 'forget_memory',
        description: 'Permanently delete a specific memory by key.',
        inputSchema: {
          type: 'object',
          properties: {
            key: { type: 'string', description: 'The memory key to delete' },
          },
          required: ['key'],
        },
      },
      {
        name: 'memory_summary',
        description:
          'Get a high-level overview of what the agent knows — total count, top tags, ' +
          'most important memories, and access statistics. Good for orientation at session start.',
        inputSchema: {
          type: 'object',
          properties: {},
        },
      },
    ],
  }));

• src/store.ts:89-111 (helper)

  The MemoryStore.stats() helper method that computes the statistics used by the memory_summary handler. Returns MemoryStats including total count, storage file path, top 10 tags by frequency, average importance, top 3 most-accessed memories, and newest key.

    stats(): MemoryStats {
      const mems = this.data.memories;
      const tagFreq: Record<string, number> = {};
      mems.forEach(m => m.tags.forEach(t => { tagFreq[t] = (tagFreq[t] ?? 0) + 1; }));
  
      return {
        total: mems.length,
        storageFile: STORE_FILE,
        topTags: Object.entries(tagFreq)
          .sort(([, a], [, b]) => b - a)
          .slice(0, 10)
          .map(([tag, count]) => ({ tag, count })),
        avgImportance: mems.length
          ? (mems.reduce((a, m) => a + m.importance, 0) / mems.length).toFixed(1)
          : '0.0',
        mostAccessed: [...mems]
          .sort((a, b) => b.accessCount - a.accessCount)
          .slice(0, 3)
          .map(m => ({ key: m.key, accessCount: m.accessCount })),
        newest: mems.length > 0 ? mems[mems.length - 1].key : null,
      };
    }
  }