Memory File Statistics
memory_statsRead-onlyIdempotent
Get detailed statistics and optimization status of a memory file to monitor memory usage and efficiency.
Instructions
Get detailed statistics and optimization status for a memory file.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| memory_file | No |
Output Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| result | Yes |
Implementation Reference
- src/mode_manager_mcp/tools/memory_tools.py:96-160 (registration)The 'memory_stats' tool is registered as a FastMCP tool at line 96-97 with the @app.tool decorator. The handler function 'memory_stats' (line 113) formats and returns detailed statistics about a memory file by calling optimizer.get_memory_stats().
@app.tool( name="memory_stats", description="Get detailed statistics and optimization status for a memory file.", tags={"public", "memory"}, annotations={ "idempotentHint": True, "readOnlyHint": True, "title": "Memory File Statistics", "parameters": { "memory_file": "Optional path to specific memory file. If not provided, will show stats for the user's main memory file.", }, "returns": "Returns comprehensive statistics including file size, entry count, optimization eligibility, and configuration settings.", }, meta={ "category": "memory", }, ) def memory_stats( memory_file: Annotated[Optional[str], "Path to memory file to analyze"] = None, ) -> str: """Get detailed statistics about a memory file.""" try: # Determine which file to analyze if memory_file: file_path = Path(memory_file) if not file_path.exists(): return f"Error: Memory file not found: {memory_file}" else: # Use default user memory file user_memory_path = instruction_manager.get_memory_file_path() if not user_memory_path.exists(): return "No user memory file found" file_path = user_memory_path # Get stats optimizer = MemoryOptimizer(instruction_manager) stats = optimizer.get_memory_stats(file_path) if "error" in stats: return str(stats["error"]) # Format stats message message = "📊 **Memory File Statistics**\n\n" message += f"📁 **File**: `{stats['file_path']}`\n" message += f"📏 **Size**: {stats['file_size_bytes']:,} bytes\n" message += f"🎯 **Tokens**: {stats['current_tokens']:,} (Last optimized: {stats['last_optimized_tokens']:,})\n" message += f"📈 **Growth**: {stats['token_growth_percent']}% since last optimization\n" message += f"📝 **Entries**: {stats['current_entries']}\n" message += f"🔄 **Last Optimized**: {stats['last_optimized'] or 'Never'}\n" message += f"⚡ **Optimization Version**: {stats['optimization_version']}\n\n" message += "⚙️ **Configuration**:\n" message += f"• Auto-optimize: {'✅ Enabled' if stats['auto_optimize_enabled'] else '❌ Disabled'}\n" threshold_percent = int((stats["token_growth_threshold"] - 1.0) * 100) message += f"• Token growth threshold: {threshold_percent}% ({stats['token_growth_threshold']})\n\n" message += "🎯 **Optimization Status**:\n" message += f"• Eligible: {'✅ Yes' if stats['optimization_eligible'] else '❌ No'}\n" message += f"• Reason: {stats['optimization_reason']}\n" message += f"• New entries since last optimization: {stats['entries_since_last_optimization']}" return message except Exception as e: return f"Error getting memory stats: {str(e)}" - The handler function 'memory_stats' determines the file path, creates a MemoryOptimizer instance, calls get_memory_stats() on it, and formats the returned stats into a human-readable string message.
def memory_stats( memory_file: Annotated[Optional[str], "Path to memory file to analyze"] = None, ) -> str: """Get detailed statistics about a memory file.""" try: # Determine which file to analyze if memory_file: file_path = Path(memory_file) if not file_path.exists(): return f"Error: Memory file not found: {memory_file}" else: # Use default user memory file user_memory_path = instruction_manager.get_memory_file_path() if not user_memory_path.exists(): return "No user memory file found" file_path = user_memory_path # Get stats optimizer = MemoryOptimizer(instruction_manager) stats = optimizer.get_memory_stats(file_path) if "error" in stats: return str(stats["error"]) # Format stats message message = "📊 **Memory File Statistics**\n\n" message += f"📁 **File**: `{stats['file_path']}`\n" message += f"📏 **Size**: {stats['file_size_bytes']:,} bytes\n" message += f"🎯 **Tokens**: {stats['current_tokens']:,} (Last optimized: {stats['last_optimized_tokens']:,})\n" message += f"📈 **Growth**: {stats['token_growth_percent']}% since last optimization\n" message += f"📝 **Entries**: {stats['current_entries']}\n" message += f"🔄 **Last Optimized**: {stats['last_optimized'] or 'Never'}\n" message += f"⚡ **Optimization Version**: {stats['optimization_version']}\n\n" message += "⚙️ **Configuration**:\n" message += f"• Auto-optimize: {'✅ Enabled' if stats['auto_optimize_enabled'] else '❌ Disabled'}\n" threshold_percent = int((stats["token_growth_threshold"] - 1.0) * 100) message += f"• Token growth threshold: {threshold_percent}% ({stats['token_growth_threshold']})\n\n" message += "🎯 **Optimization Status**:\n" message += f"• Eligible: {'✅ Yes' if stats['optimization_eligible'] else '❌ No'}\n" message += f"• Reason: {stats['optimization_reason']}\n" message += f"• New entries since last optimization: {stats['entries_since_last_optimization']}" return message except Exception as e: return f"Error getting memory stats: {str(e)}" - The 'get_memory_stats' method on MemoryOptimizer class that collects all statistics about a memory file: file size, entry count, token count, last optimized info, token growth, optimization eligibility, and configuration settings.
def get_memory_stats(self, file_path: Path) -> Dict[str, Any]: """ Get statistics about a memory file. Returns metadata and file information for user inspection. """ try: metadata = self._get_memory_metadata(file_path) frontmatter, content = parse_frontmatter_file(file_path) current_entries = self._count_memory_entries(content) file_size = file_path.stat().st_size # Count current tokens full_content = "---\n" for key, value in frontmatter.items(): if isinstance(value, str) and ('"' in value or "'" in value): full_content += f'{key}: "{value}"\n' else: full_content += f"{key}: {value}\n" full_content += f"---\n{content}" current_tokens = self._count_tokens(full_content) # Calculate optimization eligibility should_optimize, reason = self._should_optimize_memory(file_path, metadata) # Calculate token growth last_optimized_tokens = metadata.get("lastOptimizedTokenCount", 0) token_growth = 0.0 if last_optimized_tokens > 0: token_growth = ((current_tokens - last_optimized_tokens) / last_optimized_tokens) * 100 return { "file_path": str(file_path), "file_size_bytes": file_size, "current_entries": current_entries, "current_tokens": current_tokens, "last_optimized": metadata.get("lastOptimized"), "last_optimized_tokens": last_optimized_tokens, "token_growth_percent": round(token_growth, 1), "optimization_version": metadata.get("optimizationVersion", 0), "auto_optimize_enabled": metadata.get("autoOptimize", True), "token_growth_threshold": metadata.get("tokenGrowthThreshold", 1.20), "optimization_eligible": should_optimize, "optimization_reason": reason, "entries_since_last_optimization": current_entries - metadata.get("entryCount", 0), } except Exception as e: return {"error": f"Could not read memory file stats: {e}"} - The tool annotation/configuration block defining the memory_stats tool's name, description, tags, parameters schema, and return type information.
@app.tool( name="memory_stats", description="Get detailed statistics and optimization status for a memory file.", tags={"public", "memory"}, annotations={ "idempotentHint": True, "readOnlyHint": True, "title": "Memory File Statistics", "parameters": { "memory_file": "Optional path to specific memory file. If not provided, will show stats for the user's main memory file.", }, "returns": "Returns comprehensive statistics including file size, entry count, optimization eligibility, and configuration settings.", }, meta={ "category": "memory", }, )