MemoryMaintenanceMiddleware

Middleware that performs periodic memory maintenance after each agent call.

Fires on the agent invocation completion (via onAgent doOnComplete, after MemoryFlushMiddleware) and is throttled by a configurable minimum gap so it does not run on every single call. The maintenance is fire-and-forget: the agent stream completes immediately while the maintenance runs on a background scheduler.

Maintenance steps executed in order:

• Expire daily memory files older than dailyFileRetentionDays by moving them to memory/archive/.

• Run LLM-based consolidation (MemoryConsolidator#consolidate) if a consolidator is configured.

• Prune session log files older than sessionRetentionDays.

The throttle window is tracked per isolation key, which matches the memory data isolation in use:

• IsolationScope#USER (default) — one window per userId.

• IsolationScope#SESSION — one window per sessionId.

• IsolationScope#AGENT / IsolationScope#GLOBAL — one shared window for the whole agent instance (prevents concurrent maintenance races on shared memory files).