MemoryFlushMiddleware

Middleware that triggers memory flush and message offload at the end of each agent call.

Runs in #onAgent's doOnComplete so long-term memories are extracted and persisted after every call, even when conversation compaction was not triggered during that call. The flush is fire-and-forget: the agent stream completes immediately while the extraction runs on a background scheduler. When CompactionMiddleware is active, it handles flush/offload for the messages it summarizes; this middleware covers the remaining tail of messages that were kept verbatim.

Flush is gated by a MemoryConfig.FlushTrigger:

• MemoryConfig.FlushMode#ALWAYS (default) — flush after every call.

• MemoryConfig.FlushMode#NEVER — never flush via this middleware. The CompactionMiddleware and overflow-recovery paths still run their own flush when they fire.

• MemoryConfig.FlushMode#THROTTLED — flush at most once per MemoryConfig.FlushTrigger#minGap().

Session transcript append is not handled here — see TranscriptMiddleware, which runs independently of memory flush so history stays complete even when flush is disabled.

Concurrent flushes for the same isolation key are serialised: at most one flush runs per key at a time, and pending flushes of the same conversation coalesce into a single queued task, because a queued task reads the conversation state only when it executes and the newest task therefore subsumes the ones it replaces. Flushes of distinct conversations under the same key are queued separately.

The class is thread-safe: instances hold only configuration, and the per-key queues live in a static map and are synchronised internally.

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 flush races on shared memory files).