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 69.23077% with 40 lines in your changes missing coverage. Please review.

Files with missing lines	Patch %	Lines
...harness/agent/memory/MemoryOperationScheduler.java	70.00%	10 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	69.23%	2 Missing and 2 partials ⚠️

📢 Thoughts on this report? Let us know!

[oss-maintainer]

LGTM. Looks good.

---

Automated review by "github-manager-bot"