feat(harness): support ordered async memory writes

[March-77]

Fixes #2334

Problem / root cause

MemoryFlushMiddleware and MemoryMaintenanceMiddleware append LLM-backed work with concatWith, so an otherwise completed agent call holds the session gate until memory extraction and consolidation finish. A naive fire-and-forget subscription would remove that latency but could reorder writes for concurrent turns and lose accepted work during shutdown.

Changes

• add MemoryConfig.ExecutionMode.ASYNC as an opt-in while retaining BLOCKING as the compatibility default
• queue post-call flush and maintenance by the configured isolation key, preserving per-user/session order while allowing independent keys to run concurrently
• snapshot the completed turn before enqueueing and offload raw session JSONL before optional LLM extraction
• drain accepted memory operations from HarnessAgent.close() before workspace resources close
• document the async lifecycle and configuration in English and Chinese memory guides

User impact

Latency-sensitive streaming and orchestration can configure .executionMode(MemoryConfig.ExecutionMode.ASYNC) so the agent Flux completes without waiting for memory LLM calls. Writes for the same isolation key stay ordered. Existing applications retain blocking completion behavior unless they opt in.

Tests

• mvn -pl agentscope-harness -am -Djacoco.skip=true -Dtest=MemoryConfigTest,MemoryOperationSchedulerTest,MemoryMaintenanceAsyncTest -Dsurefire.failIfNoSpecifiedTests=false test — 13 passed
• mvn -pl agentscope-harness -DskipTests spotless:check — passed
• broader Harness run compiled and executed 582 tests; 11 existing @TempDir cleanup errors reproduced in the session-tree mirror path tracked by [Bug]: LocalFilesystemPersonalAssistantExampleTest flaky JUnit @TempDir cleanup race with session-tree-mirror thread #2251 / PR fix(harness): drain session-tree-mirror on HarnessAgent.close #2301, with no assertion failures from this change

Compatibility / risk

BLOCKING remains the default. Async mode requires applications to close HarnessAgent during shutdown; close drains all accepted operations. The scheduler serializes work only within an isolation key, so unrelated users/sessions are not globally bottlenecked.

[codecov]

Codecov Report

❌ Patch coverage is 70.86093% with 44 lines in your changes missing coverage. Please review.

Files with missing lines	Patch %	Lines
...harness/agent/memory/MemoryOperationScheduler.java	71.42%	13 Missing and 5 partials ⚠️
...arness/agent/middleware/MemoryFlushMiddleware.java	62.16%	11 Missing and 3 partials ⚠️
.../agent/middleware/MemoryMaintenanceMiddleware.java	65.00%	5 Missing and 2 partials ⚠️
...java/io/agentscope/harness/agent/HarnessAgent.java	64.28%	3 Missing and 2 partials ⚠️

📢 Thoughts on this report? Let us know!

[oss-maintainer]

LGTM. Looks good.

---

Automated review by "github-manager-bot"

[zouyx]

I think this class may require overload protection.
If LLM reponses slow, will too many async tasks in tails, and cause CPU or memory overload.
What do you think?

[March-77]

Good catch. The previous per-key future chains were unbounded, so a slow memory LLM could retain operations and captured request state indefinitely. Commit 97c0111 adds a fair global bound over running + queued async memory operations (default 256, configurable with maxPendingMemoryOperations). When saturated, submitters wait for capacity, which propagates backpressure instead of dropping writes; accepted operations remain serialized per isolation key, and different keys still execute concurrently. Shutdown rejects capacity waiters after close begins and continues waiting for all already accepted work.

Added concurrent/boundary coverage for saturation backpressure, release/acceptance after capacity returns, close racing with a blocked submitter, invalid capacity, same-key ordering, and cross-key concurrency. Spotless passes; the focused scheduler/config/async-maintenance suite passes 16/16. The full core suite passes 2218 tests; three unrelated macOS temp-directory cleanup races in the harness suite passed when their two test classes were rerun (14/14).