documcp

Instructions

Implementation Reference

• src/memory/index.ts:788-804 (registration)

  Registration of the 'memory_optimization_metrics' tool in the memoryTools export array, defining name, description, and input schema.

  {
    name: "memory_optimization_metrics",
    description: "Get comprehensive optimization metrics and recommendations",
    inputSchema: {
      type: "object",
      properties: {
        includeRecommendations: { type: "boolean", default: true },
        timeRange: {
          type: "object",
          properties: {
            start: { type: "string", format: "date-time" },
            end: { type: "string", format: "date-time" },
          },
        },
      },
    },
  },

• src/memory/pruning.ts:752-780 (handler)

  Primary handler logic for memory optimization metrics via MemoryPruningSystem.getOptimizationMetrics(), computing key metrics like storage size, compression ratio, and entry counts.

  async getOptimizationMetrics(): Promise<OptimizationMetrics> {
    const allEntries = await this.storage.getAll();
    const totalEntries = allEntries.length;
  
    // Calculate storage size (approximate)
    const storageSize =
      allEntries.reduce((total, entry) => {
        return total + JSON.stringify(entry).length;
      }, 0) /
      (1024 * 1024); // Convert to MB
  
    // Calculate index size (approximate)
    const indexSize = (totalEntries * 100) / (1024 * 1024); // Rough estimate
  
    // Calculate compression ratio
    const compressedEntries = allEntries.filter((e) => this.isCompressed(e));
    const compressionRatio = compressedEntries.length / totalEntries;
  
    return {
      totalEntries,
      storageSize,
      indexSize,
      compressionRatio,
      duplicatesRemoved: 0, // Would be tracked during runtime
      entriesPruned: 0, // Would be tracked during runtime
      performanceGain: 0, // Would be calculated based on before/after metrics
      lastOptimization: new Date(),
    };
  }

• src/memory/pruning.ts:828-880 (helper)

  Supporting method getPruningRecommendations() that generates optimization recommendations based on current metrics, matching the tool's includeRecommendations option.

  async getPruningRecommendations(): Promise<{
    shouldPrune: boolean;
    reasons: string[];
    estimatedSavings: number;
    recommendedPolicy: Partial<PruningPolicy>;
  }> {
    const metrics = await this.getOptimizationMetrics();
    const reasons: string[] = [];
    let shouldPrune = false;
    let estimatedSavings = 0;
  
    // Check storage size
    if (metrics.storageSize > this.defaultPolicy.maxSize * 0.8) {
      shouldPrune = true;
      reasons.push(
        `Storage size (${metrics.storageSize.toFixed(2)}MB) approaching limit`,
      );
      estimatedSavings += metrics.storageSize * 0.2;
    }
  
    // Check entry count
    if (metrics.totalEntries > this.defaultPolicy.maxEntries * 0.8) {
      shouldPrune = true;
      reasons.push(`Entry count (${metrics.totalEntries}) approaching limit`);
    }
  
    // Check compression ratio
    if (metrics.compressionRatio < 0.3) {
      reasons.push("Low compression ratio indicates optimization opportunity");
      estimatedSavings += metrics.storageSize * 0.15;
    }
  
    // Time-based recommendation
    const daysSinceLastOptimization =
      (Date.now() - metrics.lastOptimization.getTime()) / (24 * 60 * 60 * 1000);
    if (daysSinceLastOptimization > 7) {
      shouldPrune = true;
      reasons.push("Regular maintenance window (weekly optimization)");
    }
  
    return {
      shouldPrune,
      reasons,
      estimatedSavings,
      recommendedPolicy: {
        maxAge: Math.max(30, this.defaultPolicy.maxAge - 30), // More aggressive if needed
        compressionThreshold: Math.max(
          7,
          this.defaultPolicy.compressionThreshold - 7,
        ),
      },
    };
  }

• src/memory/pruning.ts:21-30 (schema)

  TypeScript interface defining the structure of OptimizationMetrics returned by the tool implementation.

  export interface OptimizationMetrics {
    totalEntries: number;
    storageSize: number;
    indexSize: number;
    compressionRatio: number;
    duplicatesRemoved: number;
    entriesPruned: number;
    performanceGain: number;
    lastOptimization: Date;
  }