Release 0.12.0: Comprehensive Memory Management and Migration System

(Updated: )
Release Notes › Architecture
, , , ,

We’re excited to announce version 0.12.0, which introduces a comprehensive memory management system that brings enterprise-grade memory handling capabilities to the Screeps GPT bot. This release addresses a critical infrastructure gap by implementing automated garbage collection, schema versioning, and real-time memory utilization monitoring.

Overview

Managing memory effectively is crucial in Screeps, where the 2MB memory limit can quickly become a bottleneck for complex bots. Previously, the bot lacked systematic memory cleanup and migration capabilities, leading to potential memory bloat and fragility when memory structures needed to evolve. This release solves these problems with three integrated subsystems that work together to maintain memory health.

Key Features

1. Memory Garbage Collection

The new MemoryGarbageCollector provides intelligent, automated cleanup of stale data:

  • Orphaned Room Cleanup: Automatically removes data for inactive or abandoned rooms after a configurable retention period (default: 10,000 ticks)
  • Report Rotation: Prevents memory bloat by rotating old system evaluation reports (default: 500 ticks retention)
  • CPU-Aware Incremental Processing: Limits cleanup operations per tick (default: 10 items) to avoid CPU spikes
  • Configurable Schedule: Runs every 10 ticks by default, fully customizable via kernel configuration

2. Schema Migration System

The MemoryMigrationManager brings version control to memory structures:

  • Version Tracking: Introduces Memory.version field to track schema versions across deployments
  • Migration Registry: Declarative system for defining version-specific upgrade handlers
  • Automated Execution: Migrations run automatically on version changes with comprehensive error handling
  • Integrity Validation: Post-migration checks ensure memory structure correctness
  • Built-in Migrations: Includes initial migration for version tracking initialization

3. Memory Utilization Monitoring

The MemoryUtilizationMonitor provides real-time visibility into memory usage:

  • Subsystem Breakdown: Tracks memory usage per component (rooms, creeps, structures, etc.)
  • Configurable Thresholds: Warning (70%) and critical (90%) alerts for proactive monitoring
  • Allocation Checks: canAllocate() method prevents memory overflow before allocation
  • Memory Budgeting: Per-subsystem budget allocation via getBudget() method
  • Human-Readable Output: Formatted byte sizes for easy monitoring dashboard integration

Technical Implementation

Architecture Decisions

Why Three Separate Components?

We deliberately chose to separate garbage collection, migrations, and monitoring into distinct classes rather than a monolithic memory manager. This design provides:

  1. Single Responsibility Principle: Each component has a clear, focused purpose
  2. Composability: Components can be enabled/disabled independently via kernel configuration
  3. Testability: Each subsystem can be unit tested in isolation (22 new unit tests added)
  4. Extensibility: New migration types or GC strategies can be added without touching unrelated code

Integration with Kernel Orchestration

The memory management system integrates seamlessly with the existing Kernel lifecycle:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
// In src/runtime/bootstrap/Kernel.ts
class Kernel {
  private memoryMigrationManager: MemoryMigrationManager;
  private memoryGarbageCollector: MemoryGarbageCollector;
  private memoryUtilizationMonitor: MemoryUtilizationMonitor;

  public run(): void {
    // 1. Migrations run first (version changes)
    this.memoryMigrationManager.runMigrations();

    // 2. Normal runtime operations...

    // 3. Garbage collection (periodic, CPU-aware)
    this.memoryGarbageCollector.collect();

    // 4. Monitoring (measures current state)
    const utilization = this.memoryUtilizationMonitor.measure();

    // 5. Evaluation receives memory metrics
    this.evaluator.evaluate({ memoryUtilization: utilization });
  }
}

Performance Considerations

Memory management operations are designed to have minimal CPU impact:

  • Garbage Collection: ~0.5-2 CPU per collection cycle (incremental processing)
  • Migration Execution: One-time cost on version changes only
  • Utilization Monitoring: ~0.1-0.3 CPU (lightweight measurement)

The incremental nature of garbage collection is particularly important—rather than processing all stale data at once (which could cause CPU spikes), the system processes a configurable maximum per tick and continues across multiple ticks if needed.

SystemEvaluator Integration

The SystemEvaluator now includes memory health monitoring as a first-class concern:

  • Memory Utilization Findings: Generates findings with appropriate severity levels (warning/critical)
  • Subsystem Analysis: Reports the largest memory consumers during critical alerts
  • Actionable Recommendations: Suggests GC tuning and retention policy adjustments

This integration ensures memory issues are caught early and surfaced through the existing evaluation and reporting infrastructure.

Migration Guide

Enabling Memory Management

Memory management is enabled by default in the kernel configuration. To customize behavior:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
// In src/runtime/bootstrap/Kernel.ts
const kernelConfig = {
  memoryManagement: {
    garbageCollection: {
      enabled: true,
      interval: 10, // ticks between collections
      roomRetention: 10000, // ticks to retain room data
      reportRetention: 500, // ticks to retain reports
      maxCleanupPerTick: 10 // max items per collection
    },
    monitoring: {
      warningThreshold: 0.7, // 70% utilization
      criticalThreshold: 0.9 // 90% utilization
    }
  }
};

Adding Custom Migrations

To add a migration for schema changes:

1
2
3
4
5
6
7
8
// Register migration in MemoryMigrationManager
migrationManager.registerMigration("0.13.0", memory => {
  // Upgrade memory structure for v0.13.0
  if (!memory.newFeature) {
    memory.newFeature = { enabled: false };
  }
  return memory;
});

Testing and Quality Assurance

This release includes extensive test coverage to ensure reliability:

  • 22 New Unit Tests: Covering all three memory management components
  • Test Coverage: Memory bootstrapping, GC behavior, migration execution, monitoring thresholds
  • Regression Prevention: Tests validate edge cases like empty memory, missing subsystems, and concurrent operations
  • All 231 Unit Tests Pass: Full test suite remains green after integration

Documentation

Comprehensive documentation has been added to docs/runtime/memory-management.md covering:

  • Architecture overview and component descriptions
  • Configuration options and usage examples
  • Integration patterns with kernel and evaluator
  • Best practices for GC, migrations, and optimization
  • Troubleshooting guide and performance considerations

Breaking Changes

None. This release is fully backward compatible—memory management features integrate seamlessly with existing runtime code.

Performance Impact

Minimal. The memory management system is designed for efficiency:

  • Garbage collection uses incremental processing to avoid CPU spikes
  • Monitoring operations are lightweight (< 0.5 CPU per tick)
  • Migrations run only on version changes, not every tick

What’s Next

With solid memory management foundations in place, upcoming releases will focus on:

  • Automatic Memory Optimization: AI-driven recommendations for memory structure improvements
  • Memory Profiling: Detailed analysis of memory growth patterns over time
  • Predictive Alerts: Machine learning models to predict memory issues before they occur
  • Memory Replay: Ability to replay memory states for debugging and testing
  • Issue #490: Comprehensive Memory Management and Migration System

Acknowledgments

This release represents a significant infrastructure improvement that will enable more sophisticated bot behaviors while maintaining stability and performance. The memory management system provides the foundation for future autonomous memory optimization capabilities.

Full Changelog: 0.12.0 on GitHub