Mode Manager MCP

Instructions

Implementation Reference

• src/mode_manager_mcp/tools/memory_tools.py:37-95 (handler)

  The main handler function for the 'optimize_memory' tool. It resolves the memory file path (defaulting to user's main memory), instantiates MemoryOptimizer, calls optimize_memory_if_needed with force option, and formats/returns the detailed result message.

  async def optimize_memory(
      ctx: Context,
      memory_file: Annotated[Optional[str], "Path to memory file to optimize"] = None,
      force: Annotated[bool, "Force optimization regardless of criteria"] = False,
  ) -> str:
      """Manually optimize a memory file using AI sampling."""
      if read_only:
          return "Error: Server is running in read-only mode"
  
      try:
          # Determine which file to optimize
          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 "Error: No user memory file found to optimize"
              file_path = user_memory_path
  
          # Create optimizer and run optimization
          optimizer = MemoryOptimizer(instruction_manager)
          result = await optimizer.optimize_memory_if_needed(file_path, ctx, force=force)
  
          # Format result message
          status = result.get("status", "unknown")
          if status == "optimized":
              entries_before = result.get("entries_before", "unknown")
              entries_after = result.get("entries_after", "unknown")
              backup_created = result.get("backup_created", False)
  
              message = f"✅ Memory optimization completed successfully!\n"
              message += f"📊 Entries: {entries_before} → {entries_after}\n"
              message += f"🔄 Method: {result.get('method', 'ai')}\n"
              message += f"💾 Backup created: {'Yes' if backup_created else 'No'}\n"
              message += f"📝 Reason: {result.get('reason', 'Manual optimization')}"
  
          elif status == "metadata_updated":
              message = f"📝 Memory metadata updated (AI optimization unavailable)\n"
              message += f"💾 Backup created: {'Yes' if result.get('backup_created', False) else 'No'}\n"
              message += f"📝 Reason: {result.get('reason', 'Manual optimization')}"
  
          elif status == "skipped":
              message = f"⏭️ Optimization skipped: {result.get('reason', 'Unknown reason')}\n"
              message += f"💡 Use force=True to optimize anyway"
  
          elif status == "error":
              message = f"❌ Optimization failed: {result.get('reason', 'Unknown error')}"
  
          else:
              message = f"🔍 Optimization result: {status}"
  
          return message
  
      except Exception as e:
          return f"Error during memory optimization: {str(e)}"

• src/mode_manager_mcp/tools/memory_tools.py:19-36 (registration)

  Registration of the 'optimize_memory' tool using @app.tool decorator, including schema for parameters (memory_file optional str, force bool), description, tags, and metadata.

  @app.tool(
      name="optimize_memory",
      description="Manually optimize a memory file using AI to reorganize and consolidate entries while preserving all information.",
      tags={"public", "memory"},
      annotations={
          "idempotentHint": False,
          "readOnlyHint": False,
          "title": "Optimize Memory File",
          "parameters": {
              "memory_file": "Optional path to specific memory file. If not provided, will optimize the user's main memory file.",
              "force": "Force optimization even if criteria are not met. Defaults to False.",
          },
          "returns": "Returns detailed results of the optimization process including status, entries before/after, and backup information.",
      },
      meta={
          "category": "memory",
      },
  )

• src/mode_manager_mcp/tools/memory_tools.py:23-32 (schema)

  Input/output schema definition in tool annotations, specifying parameters and return description.

  annotations={
      "idempotentHint": False,
      "readOnlyHint": False,
      "title": "Optimize Memory File",
      "parameters": {
          "memory_file": "Optional path to specific memory file. If not provided, will optimize the user's main memory file.",
          "force": "Force optimization even if criteria are not met. Defaults to False.",
      },
      "returns": "Returns detailed results of the optimization process including status, entries before/after, and backup information.",
  },

• src/mode_manager_mcp/memory_optimizer.py:237-323 (helper)

  Core helper method called by the tool handler. Determines if optimization needed (size, entries, time thresholds), performs AI-based content reorganization using ctx.sample, updates frontmatter metadata, creates backup, returns status/results.

  async def optimize_memory_if_needed(self, file_path: Path, ctx: Context, force: bool = False) -> Dict[str, Any]:
      """
      Main optimization method with full backward compatibility.
  
      Args:
          file_path: Path to memory file
          ctx: FastMCP context for AI sampling
          force: Force optimization regardless of criteria
  
      Returns:
          Dict with optimization results
      """
      try:
          # Get metadata (with backward compatibility)
          metadata = self._get_memory_metadata(file_path)
  
          # Check if optimization is needed
          if not force:
              should_optimize, reason = self._should_optimize_memory(file_path, metadata)
              if not should_optimize:
                  return {"status": "skipped", "reason": reason, "metadata": metadata}
          else:
              reason = "Forced optimization"
  
          # Read current content
          frontmatter, content = parse_frontmatter_file(file_path)
          full_content = f"---\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}"
  
          logger.info(f"Starting memory optimization: {reason}")
  
          # Try AI optimization
          optimized_content = await self._optimize_memory_with_ai(ctx, full_content)
  
          if optimized_content:
              # Parse optimized content directly from string
              optimized_frontmatter, optimized_body = parse_frontmatter(optimized_content)
  
              # Update metadata in the optimized frontmatter
              entry_count = self._count_memory_entries(optimized_body)
              optimized_frontmatter.update(
                  {
                      "lastOptimized": datetime.datetime.now(datetime.timezone.utc).isoformat(),
                      "entryCount": entry_count,
                      "optimizationVersion": frontmatter.get("optimizationVersion", 0) + 1,
                  }
              )
  
              # Preserve user preferences from original frontmatter
              for key in ["autoOptimize", "sizeThreshold", "entryThreshold", "timeThreshold"]:
                  if key in frontmatter:
                      optimized_frontmatter[key] = frontmatter[key]
                  elif key not in optimized_frontmatter:
                      # Set sensible defaults for new files
                      defaults = {"autoOptimize": True, "sizeThreshold": 50000, "entryThreshold": 20, "timeThreshold": 7}
                      optimized_frontmatter[key] = defaults[key]
  
              # Write optimized content
              success = write_frontmatter_file(file_path, optimized_frontmatter, optimized_body, create_backup=True)
  
              # Determine if backup was actually created (skipped for git repos)
              backup_created = False if _is_in_git_repository(file_path) else success
  
              if success:
                  logger.info(f"Memory optimization completed successfully")
                  return {"status": "optimized", "reason": reason, "method": "ai", "entries_before": metadata.get("entryCount", 0), "entries_after": entry_count, "backup_created": backup_created}
              else:
                  return {"status": "error", "reason": "Failed to write optimized content"}
          else:
              # AI optimization failed, just update metadata
              logger.info("AI optimization unavailable, updating metadata only")
              success = self._update_metadata(file_path, content)
  
              # Determine if backup was actually created (skipped for git repos)
              backup_created = False if _is_in_git_repository(file_path) else success
  
              return {"status": "metadata_updated", "reason": reason, "method": "metadata_only", "ai_available": False, "backup_created": backup_created}
  
      except Exception as e:
          logger.error(f"Memory optimization failed: {e}")
          return {"status": "error", "reason": str(e)}

• src/mode_manager_mcp/memory_optimizer.py:190-236 (helper)

  Helper that performs the actual AI optimization: crafts detailed prompt for memory reorganization/consolidation, calls ctx.sample, validates output preserves structure.

      async def _optimize_memory_with_ai(self, ctx: Context, content: str) -> Optional[str]:
          """Safely optimize memory content using AI sampling with comprehensive error handling."""
          try:
              response = await ctx.sample(
                  f"""Please optimize this AI memory file by:
                  
  1. **Preserve ALL information** - Do not delete any memories or important details
  2. **Remove duplicates** - Consolidate identical or very similar entries
  3. **Organize by sections** - Group related memories under clear headings:
     - ## Personal Context (name, location, role, etc.)
     - ## Professional Context (team, goals, projects, etc.) 
     - ## Technical Preferences (coding styles, tools, workflows)
     - ## Communication Preferences (style, feedback preferences)
     - ## Universal Laws (strict rules that must always be followed)
     - ## Policies (guidelines and standards)
     - ## Suggestions/Hints (recommendations and tips)
     - ## Memories/Facts (chronological events and information)
  4. **Maintain timestamps** - Keep all original timestamps for traceability
  5. **Improve formatting** - Use consistent markdown formatting
  6. **Preserve frontmatter structure** - Keep the YAML header intact
  
  Return ONLY the optimized content (including frontmatter), nothing else:
  
  {content}""",
                  temperature=0.1,  # Very low for consistency
                  max_tokens=4000,
                  model_preferences=["gpt-4", "claude-3-sonnet"],  # Prefer more reliable models
              )
  
              if response and hasattr(response, "text"):
                  text_attr = getattr(response, "text", None)
                  optimized_content = str(text_attr).strip() if text_attr else None
  
                  # Basic validation - ensure we still have a memories section
                  if optimized_content and ("## Memories" in optimized_content or "# Personal" in optimized_content):
                      return optimized_content
                  else:
                      logger.warning("AI optimization removed essential sections, reverting to original")
                      return None
              else:
                  logger.warning(f"AI optimization returned unexpected type or no text: {type(response)}")
                  return None
  
          except Exception as e:
              logger.info(f"AI optimization failed: {e}")
              return None