Build and run agents you can see, understand and trust.
Python agentchatbotlarge-language-modelsllmllm-agentmcpmulti-agentmulti-modalreact-agentrealtime-agentvoice-agentvoice-assistant
feat(middleware): add ReMe long-term memory middleware (#1972)
Sen Huang922e673b0e3d
diff --git a/README.md b/README.mdindex d3ab8dcd1..f49f170c9 100644--- a/README.md+++ b/README.md@@ -73,6 +73,7 @@ rather than constraining them with strict prompts and opinionated orchestrations## News<!-- BEGIN NEWS -->+- **[2026-07] `INTE`:** ReMe long-term memory supported. [Example](https://github.com/agentscope-ai/agentscope/tree/main/examples/long_term_memory/reme) | [Docs](https://docs.agentscope.io/latest/en/building-blocks/long-term-memory)- **[2026-06] `FEAT`:** Agentic Memory supported. [Example](https://github.com/agentscope-ai/agentscope/tree/main/examples/long_term_memory/agentic_memory) | [Docs](https://docs.agentscope.io/latest/en/building-blocks/long-term-memory)- **[2026-06] `FEAT`:** Distributed & Multi-Tenancy & Multi-Session RAG service supported. [Docs](https://docs.agentscope.io/latest/en/deploy/agent-team)- **[2026-06] `FEAT`:** RAG supported. [Example](https://github.com/agentscope-ai/agentscope/tree/main/examples/rag) | [Docs](https://docs.agentscope.io/latest/en/building-blocks/rag)diff --git a/README_zh.md b/README_zh.mdindex 479e4238e..e310fd270 100644--- a/README_zh.md+++ b/README_zh.md@@ -79,6 +79,7 @@ AgentScope 2.0 是一款面向生产、易于使用的智能体框架,提供## 新闻<!-- BEGIN NEWS -->+- **[2026-07] `集成`:** 集成 ReMe 长期记忆。 [样例](https://github.com/agentscope-ai/agentscope/tree/main/examples/long_term_memory/reme) | [文档](https://docs.agentscope.io/latest/zh/building-blocks/long-term-memory)- **[2026-06] `功能`:** 支持 Agentic Memory。 [样例](https://github.com/agentscope-ai/agentscope/tree/main/examples/long_term_memory/agentic_memory) | [文档](https://docs.agentscope.io/latest/zh/building-blocks/long-term-memory)- **[2026-06] `功能`:** 支持分布式 & 多租户 & 多会话 RAG 服务。 [文档](https://docs.agentscope.io/latest/en/deploy/agent-team)- **[2026-06] `功能`:** 支持多模态 RAG。 [样例](https://github.com/agentscope-ai/agentscope/tree/main/examples/rag) | [文档](https://docs.agentscope.io/latest/en/building-blocks/rag)diff --git a/docs/NEWS.md b/docs/NEWS.mdindex 33a32f44d..6742ba63c 100644--- a/docs/NEWS.md+++ b/docs/NEWS.md@@ -2,6 +2,7 @@<!-- The first 10 items are automatically synced to README.md and README_zh.md via GitHub Actions. --><!-- To update news in READMEs, modify this file and push to trigger the workflow. -->+- **[2026-07] `INTE`:** ReMe long-term memory supported. [Example](https://github.com/agentscope-ai/agentscope/tree/main/examples/long_term_memory/reme) | [Docs](https://docs.agentscope.io/latest/en/building-blocks/long-term-memory)- **[2026-06] `FEAT`:** Agentic Memory supported. [Example](https://github.com/agentscope-ai/agentscope/tree/main/examples/long_term_memory/agentic_memory) | [Docs](https://docs.agentscope.io/latest/en/building-blocks/long-term-memory)- **[2026-06] `FEAT`:** Distributed & Multi-Tenancy & Multi-Session RAG service supported. [Docs](https://docs.agentscope.io/latest/en/deploy/agent-team)- **[2026-06] `FEAT`:** RAG supported. [Example](https://github.com/agentscope-ai/agentscope/tree/main/examples/rag) | [Docs](https://docs.agentscope.io/latest/en/building-blocks/rag)diff --git a/docs/NEWS_zh.md b/docs/NEWS_zh.mdindex 83a0ea686..d8a1326e6 100644--- a/docs/NEWS_zh.md+++ b/docs/NEWS_zh.md@@ -2,6 +2,7 @@<!-- The first 10 items are automatically synced to README.md and README_zh.md via GitHub Actions. --><!-- To update news in READMEs, modify this file and push to trigger the workflow. -->+- **[2026-07] `集成`:** 集成 ReMe 长期记忆。 [样例](https://github.com/agentscope-ai/agentscope/tree/main/examples/long_term_memory/reme) | [文档](https://docs.agentscope.io/latest/zh/building-blocks/long-term-memory)- **[2026-06] `功能`:** 支持 Agentic Memory。 [样例](https://github.com/agentscope-ai/agentscope/tree/main/examples/long_term_memory/agentic_memory) | [文档](https://docs.agentscope.io/latest/zh/building-blocks/long-term-memory)- **[2026-06] `功能`:** 支持分布式 & 多租户 & 多会话 RAG 服务。 [文档](https://docs.agentscope.io/latest/en/deploy/agent-team)- **[2026-06] `功能`:** 支持多模态 RAG。 [样例](https://github.com/agentscope-ai/agentscope/tree/main/examples/rag) | [文档](https://docs.agentscope.io/latest/en/building-blocks/rag)diff --git a/examples/long_term_memory/reme/README.md b/examples/long_term_memory/reme/README.mdnew file mode 100644index 000000000..3ecbcfacf--- /dev/null+++ b/examples/long_term_memory/reme/README.md@@ -0,0 +1,203 @@+# ReMe middleware example++One runnable demo (`reme_demo.py`) showing the+[ReMe](https://github.com/agentscope-ai/ReMe) middleware plugged into+an `agentscope.agent.Agent`. Drives two consecutive agent **sessions**+that share one ReMe workspace so ReMe's cross-session memory effect is+visible, and prints each middleware contribution (retrieval / tool+call / write-back) inline so you can see when each path fires.++ReMe is the AgentScope team's own file-based memory toolkit. Unlike+mem0, it is **embedded in-process** — there is no separate service to+run — and it records memory by **listening to the conversation**:+after every reply the new exchange is written back automatically via+ReMe's `auto_memory` job. The agent never saves memory itself; there+is no add tool. The demo drives ReMe with AgentScope's own DashScope+chat model (LLM-backed `auto_memory` write-back) and DashScope+embedding model (vector search), both injected into the embedded app.++ReMe's bundled `default` config searches with **BM25 (keyword) only** —+its file store ships with the vector store disabled. A long-term+*memory* demo wants **semantic** recall ("plot monthly sales" should+find a "prefers matplotlib" card), so `reme_demo.py` injects an+`embedding_model` — which turns ReMe's vector store on automatically;+see below.++## Install++```bash+# reme-ai is an optional AgentScope dependency — pull it via the extra:+pip install "agentscope[reme]"+# (equivalent to `pip install agentscope reme-ai`)++export DASHSCOPE_API_KEY=sk-...+```++## Import path++`ReMeMiddleware` is exported from the middleware package:++```python+from agentscope.middleware import ReMeMiddleware+from agentscope.tool import Toolkit+```++## Construction++The middleware builds and **owns** an embedded `reme.ReMe` app — it is+created lazily on first use and torn down by `await mw.close()`. You+configure it with plain parameters; there is no external app to manage.+User-tunable settings live on a nested `Parameters` model (the agent+service renders its JSON schema as a form):++```python+ReMeMiddleware(+ workspace_dir=".reme",+ parameters=ReMeMiddleware.Parameters(+ chat_model=my_chat_model, # injected into ReMe's LLM component,+ # drives auto_memory write-back+ embedding_model=my_embedding_model, # injected into its embedding+ # component; also turns ReMe's+ # vector store ON automatically+ mode="both",+ top_k=5,+ ),+)+```++Both models are fixed for the app's lifetime (never taken from an+agent), so the embedded app's single LLM / embedding component is+well-defined even when one middleware instance is shared across agents.++| `chat_model` / `embedding_model` | Behavior |+|:-:|---|+| provided | Injected into ReMe's default LLM / embedding components at start; only a DashScope key is needed. An `embedding_model` also enables the vector store for semantic search. |+| omitted | ReMe uses the LLM / embedding backend from its own config/credentials; search stays keyword-only. |++> **Why inject `embedding_model`?** ReMe starts its embedding+> component eagerly at `start()` — even under the BM25-only default —+> and builds it from credentials in its config. Injecting an+> AgentScope `embedding_model` bypasses that credential path, so the+> only key you need is a DashScope one. It is also what powers vector+> search: providing it flips ReMe's file store from BM25-only to the+> vector store automatically.++## How the middleware controls memory++ReMe **always** writes the new exchange back through `auto_memory`+after each reply, in every mode — `mode` only selects how the agent+*retrieves*:++### `static_control`+The middleware does the retrieval, the agent is unaware:++1. **`on_reply` (pre)** starts a background `asyncio` task that searches+ ReMe with the latest user message, running concurrently with the reply.+2. **`on_reasoning`** polls that task before each reasoning step; once it+ has finished, the middleware appends an+ `AssistantMsg(name="memory", ...)` `HintBlock` to `state.context` so+ the *next* model call sees it. Injection is **best-effort**: a+ single-shot reply (one model call) may finish before retrieval does, so+ the hint lands on a later step or is skipped for that turn — the same+ trade-off as `AgenticMemoryMiddleware`. Turns with a tool call (two or+ more reasoning steps) inject reliably.+3. **`on_reply` (post)** writes the new `(user, assistant)` exchange+ back via `auto_memory`.++The injected memory message **persists** in the agent's context across+turns. If long sessions accumulate too many, post-process with+`compress_context` or a custom middleware.++### `agent_control`+The middleware lists a single `memory_search(query, limit)` tool and+otherwise stays out of the way (auto write-back still runs). Pass it+into the agent's toolkit explicitly:++```python+mw = ReMeMiddleware(..., mode="agent_control")+agent = Agent(+ ...,+ toolkit=Toolkit(tools=await mw.list_tools()),+ middlewares=[mw],+)+```++The system prompt gets a short nudge telling the agent the search tool+exists; per-tool usage guidance comes through the standard tool schema.+No automatic retrieval.++### `both` (default)+Both retrieval paths are active: memories are auto-retrieved and+appended to the agent's context as an assistant note, AND the+`memory_search` tool (with its system-prompt hint) is exposed for+explicit on-demand search.++## Memory scoping (`session_id`)++ReMe scopes write-back by **`session_id`**, read live from+`agent.state.session_id` at hook time — never stored on the+middleware. Search runs **workspace-wide** (across every session),+which is what lets a later session recall an earlier one's memories+even with a different `session_id`. To pin a resumable session, set+the id on the agent:++```python+from agentscope.state import AgentState++agent = Agent(..., state=AgentState(session_id="alice-main"))+```++The demo does exactly this — `session-1` writes the preference,+`session-2` (a fresh agent, empty chat context) recalls it through the+shared workspace.++## Sharing one middleware across agents++Because the `session_id` is read per call (not stored) and the chat+model is fixed at construction (tied to the embedded app's single+LLM), **one** `ReMeMiddleware` can be safely shared across many agents+and sessions — build it once and pass it to each agent:++```python+mw = ReMeMiddleware(+ workspace_dir=".reme",+ chat_model=chat_model,+ embedding_model=embedding_model,+ mode="both",+)+agent_a = Agent(..., middlewares=[mw], state=AgentState(session_id="a"))+agent_b = Agent(..., middlewares=[mw], state=AgentState(session_id="b"))+```++This is what the demo does. Call `await mw.close()` on shutdown to tear+down the embedded app (AgentScope doesn't manage middleware lifecycle).++## Configuration++`config` selects a ReMe config (defaults to the bundled `"default"`,+which is auto-memory + **BM25-only** search — its file store ships with+`embedding_store: ""`). To enable **vector search**, provide an+`embedding_model` (what the demo does) — the middleware then wires+ReMe's file store to the default embedding store automatically:++```python+ReMeMiddleware(+ workspace_dir=".reme",+ parameters=ReMeMiddleware.Parameters(+ embedding_model=my_embedding_model, # turns the vector store on+ ),+)+```++ReMe's `as_llm` / `as_embedding` components are otherwise driven by+environment variables (`LLM_API_KEY`, `EMBEDDING_API_KEY`, ...) from its+own config; injecting AgentScope `chat_model` / `embedding_model`+bypasses those. If you need a config the dedicated parameters don't+expose, point `config` at your own ReMe config file. See ReMe's+`default.yaml` for the full component set.++> **Note (indexing):** `auto_memory` write-back returns as soon as the+> daily card is written to disk; the card only becomes searchable once+> ReMe indexes it. The demo forces a synchronous `reindex` after each+> write so the next read deterministically sees it, rather than relying+> on ReMe's background index loop. See `_reindex` in `reme_demo.py`.diff --git a/examples/long_term_memory/reme/reme_demo.py b/examples/long_term_memory/reme/reme_demo.pynew file mode 100644index 000000000..c40dfcaff--- /dev/null+++ b/examples/long_term_memory/reme/reme_demo.py@@ -0,0 +1,336 @@+# -*- coding: utf-8 -*-+"""ReMe middleware demo (embedded reme-ai, AgentScope-driven).++Drives two independent agent **sessions** that share one ReMe+workspace, so ReMe's cross-session memory effect is visible: session 1+states a durable preference, the middleware writes it back+automatically, and a *fresh* session-2 agent — with an empty chat+context — recalls it through ReMe.++Each turn streams events from ``agent.reply_stream`` and prints the+ones that matter:++- ``[reme → context (static)]`` — the memory note the middleware+ appended to ``state.context``. Retrieval runs in the background and the+ note is injected on a reasoning step once the search finishes, so the+ demo surfaces it the moment it appears (best-effort: a single-shot reply+ may finish before it lands)+- ``[tool call (agent)]`` — each ``memory_search`` invocation the+ agent makes on its own (there is no add tool — writing is automatic)+- ``[assistant]`` — the assistant's reply, concatenated from the+ ``TextBlockDeltaEvent`` stream+- ``[context → reme (auto)]`` — what ReMe persisted after the turn,+ surfaced by searching the workspace++The mode tag (``static`` / ``agent``) on each line tells you which+control path produced it.++Unlike mem0, ReMe is **embedded in-process** (no separate service to+run) and records memory by **listening to the conversation** — after+every reply the new exchange is written back via ReMe's ``auto_memory``+job, in *all* modes. ``mode`` only controls *retrieval*. The agent+never writes memory itself.++ReMe drives its LLM-backed ``auto_memory`` write-back and its vector+search through AgentScope models injected here — a DashScope chat model+and embedding model — so the only credential needed is a DashScope key.++Starts each run from a clean workspace so the demo is reproducible.++Requires:+ pip install "agentscope[reme]"+ export DASHSCOPE_API_KEY=sk-...+"""+import asyncio+import logging+import os+import shutil+import tempfile++from agentscope.agent import Agent+from agentscope.credential import DashScopeCredential+from agentscope.embedding import DashScopeEmbeddingModel+from agentscope.event import (+ TextBlockDeltaEvent,+ ToolCallDeltaEvent,+ ToolCallStartEvent,+ ToolResultEndEvent,+ ToolResultTextDeltaEvent,+)+from agentscope.message import UserMsg+from agentscope.middleware import ReMeMiddleware+from agentscope.model import DashScopeChatModel+from agentscope.state import AgentState+from agentscope.tool import Toolkit+++MODE = "both" # try "static_control" or "agent_control" too++# ReMe writes its memory cards and indexes here. Defaults to a fresh,+# empty random temp dir (created per run) so runs never collide and+# nothing lands in the repo. Override with REME_WORKSPACE_DIR (e.g.+# ".reme") to keep the cards around for inspection; a user-named dir is+# reused as-is and only wiped when you also set REME_DEMO_RESET=1 — the+# demo never silently deletes a directory you pointed it at (it could be+# a real ReMe workspace, a project dir, ~/.reme, ...).+_ENV_WORKSPACE = os.environ.get("REME_WORKSPACE_DIR")+WORKSPACE_DIR = _ENV_WORKSPACE or tempfile.mkdtemp(prefix="reme_demo_")++# Quiet ReMe's informational startup logs so the demo output stays+# focused on the middleware contributions we print ourselves.+logging.getLogger("reme").setLevel(logging.ERROR)+++async def _memories_in_reme(mw: ReMeMiddleware, query: str) -> list[str]:+ """Return ReMe's persisted memories matching ``query`` as strings.++ Search is workspace-wide (it spans every session), so this is the+ natural read-path for inspecting what got written back between+ turns — analogous to listing a vector store's facts.+ """+ # pylint: disable-next=protected-access+ return await mw._search(query, limit=20) # demo only — peek at state+++async def _reindex(mw: ReMeMiddleware) -> None:+ """Synchronously rebuild ReMe's search index from disk.++ ``auto_memory`` write-back returns as soon as the daily card is+ written to the workspace, but that card only becomes *searchable*+ once ReMe indexes it. ReMe normally does this in a background watch+ loop; the demo forces a synchronous ``reindex`` instead so the very+ next read deterministically sees the freshly written memory (no+ sleeping / polling for the background loop to catch up).+ """+ # pylint: disable-next=protected-access+ await mw._run_job("reindex") # demo only — make writes searchable now+++def _injected_memory_bullets(agent: Agent) -> list[str]:+ """Extract the bullet lines from the memory note the middleware+ appended to ``agent.state.context`` (if any) — strips the section+ header and intro so we see only the actual retrieved facts."""+ for msg in agent.state.context:+ if getattr(msg, "name", None) != "memory":+ continue+ hint_text = "\n".join(+ block.hint for block in msg.get_content_blocks("hint")+ )+ return [+ line[2:].strip()+ for line in hint_text.splitlines()+ if line.startswith("- ")+ ]+ return []+++async def _run_turn(agent: Agent, user_msg: UserMsg) -> str:+ """Drive one reply turn through ``agent.reply_stream`` and print+ each middleware contribution as it happens, in the order it+ happens:++ 1. ``[reme → context]`` — the retrieved memory note. The middleware+ searches ReMe in the background and injects the note on a reasoning+ step once the search finishes, so we poll ``state.context`` on every+ event and surface it the first time it appears (best-effort; a+ single-shot reply may finish before it lands).+ 2. ``ToolCallStartEvent`` / ``ToolResultEndEvent`` bracket each+ ``memory_search`` invocation the agent makes on its own+ (agent path).+ 3. ``TextBlockDeltaEvent`` carries the assistant's streamed reply+ text — concatenating every delta yields the final message+ content.++ Each printed line is tagged with the ReMe control path that+ produced it (``static`` vs ``agent``) so the demo stays readable+ in any of the three modes.+ """+ pending_args: dict[str, str] = {}+ pending_names: dict[str, str] = {}+ pending_results: dict[str, str] = {}+ text_parts: list[str] = []+ memory_announced = False++ def _announce_memory() -> None:+ """Print the static-path memory note as soon as it lands in context.++ The middleware retrieves in the background and injects the note in+ ``on_reasoning`` once the search finishes, so we poll the context on+ every event and surface it the first time it appears (best-effort:+ a single-shot reply may never inject one)."""+ nonlocal memory_announced+ if memory_announced:+ return+ injected = _injected_memory_bullets(agent)+ if not injected:+ return+ print(+ f"[reme → context (static)] retrieved "+ f"{len(injected)} memory note(s):",+ )+ for b in injected:+ print(f" ← {b}")+ memory_announced = True++ async for ev in agent.reply_stream(inputs=user_msg):+ _announce_memory()+ if isinstance(ev, ToolCallStartEvent):+ pending_names[ev.tool_call_id] = ev.tool_call_name+ pending_args[ev.tool_call_id] = ""+ pending_results[ev.tool_call_id] = ""+ elif isinstance(ev, ToolCallDeltaEvent):+ pending_args[ev.tool_call_id] += ev.delta+ elif isinstance(ev, ToolResultTextDeltaEvent):+ pending_results[ev.tool_call_id] += ev.delta+ elif isinstance(ev, ToolResultEndEvent):+ name = pending_names.pop(ev.tool_call_id, "<unknown>")+ args = pending_args.pop(ev.tool_call_id, "")+ result = pending_results.pop(ev.tool_call_id, "")+ print(f"[tool call (agent)] {name}({args}) → state={ev.state}")+ for line in result.splitlines() or [""]:+ if line:+ print(f" → {line}")+ elif isinstance(ev, TextBlockDeltaEvent):+ text_parts.append(ev.delta)++ # The note may only land on the final reasoning step, after the last+ # event we react to above — poll once more before finishing the turn.+ _announce_memory()++ return "".join(text_parts)+++def _build_agent(+ chat_model: DashScopeChatModel,+ mw: ReMeMiddleware,+ session_id: str,+ tools: list,+) -> Agent:+ """Construct a data-analysis agent pinned to ``session_id``.++ ReMe scopes write-back by ``session_id`` (read from+ ``agent.state.session_id`` at hook time), so a distinct id per+ session keeps each conversation's cards apart; search still spans+ the whole workspace, which is what bridges the two sessions.+ """+ return Agent(+ name="datascope_assistant",+ system_prompt=(+ "You are a helpful data-analysis assistant. Be concise. "+ "When the request may depend on a durable fact from a past "+ "session (a preference, a name, a prior decision), use the "+ "memory_search tool. Saving memory is automatic."+ ),+ model=chat_model,+ toolkit=Toolkit(tools=tools),+ middlewares=[mw],+ state=AgentState(session_id=session_id),+ )+++async def main() -> None:+ """Drive two cross-session agent turns and print middleware effects."""+ api_key = os.environ["DASHSCOPE_API_KEY"]++ # Start from a clean workspace so the demo is reproducible. The+ # default temp dir is already fresh (mkdtemp just created it empty),+ # so there is nothing to wipe. A user-provided REME_WORKSPACE_DIR is+ # reused as-is and only reset when REME_DEMO_RESET=1 is set — we must+ # never silently delete a directory the user named.+ if _ENV_WORKSPACE and os.environ.get("REME_DEMO_RESET") == "1":+ print("=== resetting ReMe workspace (REME_DEMO_RESET=1) ===")+ print(f" rm -rf {WORKSPACE_DIR}")+ shutil.rmtree(WORKSPACE_DIR, ignore_errors=True)+ elif _ENV_WORKSPACE:+ print(f"=== reusing ReMe workspace {WORKSPACE_DIR} ===")+ print(" (set REME_DEMO_RESET=1 to wipe it before this run)")+ else:+ print(f"=== fresh ReMe workspace {WORKSPACE_DIR} ===")++ chat_model = DashScopeChatModel(+ credential=DashScopeCredential(api_key=api_key),+ model="qwen3.7-max",+ stream=True,+ )+ embedding_model = DashScopeEmbeddingModel(+ credential=DashScopeCredential(api_key=api_key),+ model="text-embedding-v4",+ dimensions=1024, # matches ReMe's default embedding dimension+ )++ # One middleware, shared across both sessions. ReMe is embedded+ # in-process and the middleware owns its lifecycle — it builds the+ # reme.ReMe app lazily on first use and closes it on mw.close(). The+ # chat + embedding models are fixed here (they drive the embedded+ # app's single LLM for auto_memory write-back and its vector search).+ # Per-conversation state (session_id) is read live from each agent,+ # never stored on the middleware — so sharing one instance across+ # agents/sessions is safe.+ #+ # ReMe's bundled ``default`` config searches keyword-only (its file+ # store ships with ``embedding_store: ""``). For a long-term *memory*+ # demo we want semantic recall — "plot monthly sales" should find a+ # "prefers matplotlib / dark mode" card even without shared keywords —+ # so we pass an ``embedding_model``, which the middleware uses to turn+ # ReMe's vector store on automatically when it builds the app.+ mw = ReMeMiddleware(+ workspace_dir=WORKSPACE_DIR,+ parameters=ReMeMiddleware.Parameters(+ chat_model=chat_model,+ embedding_model=embedding_model,+ mode=MODE,+ top_k=5,+ ),+ )++ try:+ tools = await mw.list_tools()++ # =============================================================+ # SESSION 1 — state a durable preference; ReMe writes it back.+ # =============================================================+ print(f"\n=== SESSION 1 (mode={MODE!r}) ===")+ user_msg_1 = (+ "Hi! For any chart, please default to dark mode and use "+ "matplotlib. Also I'm based in Hangzhou."+ )+ print(f"\n[user] {user_msg_1}\n")++ agent = _build_agent(chat_model, mw, "session-1", tools)+ reply_text = await _run_turn(agent, UserMsg("alice", user_msg_1))+ print(f"\n[assistant] {reply_text}")++ # Make session 1's write-back searchable before session 2 reads+ # (see _reindex — ReMe's background indexer is not relied upon).+ print("\n(indexing the new memory card...)")+ await _reindex(mw)+ persisted = await _memories_in_reme(mw, "chart preferences location")+ print("[context → reme (auto)] workspace now holds:")+ for m in persisted:+ print(f" + {m}")++ # =============================================================+ # SESSION 2 — fresh agent, empty chat context. ReMe bridges.+ # =============================================================+ print(+ f"\n=== SESSION 2 (fresh agent, reme bridges; mode={MODE!r}) ===",+ )+ user_msg_2 = (+ "Plot me a bar chart of monthly sales — pick reasonable "+ "defaults for theme and library."+ )+ print(f"\n[user] {user_msg_2}\n")++ agent = _build_agent(chat_model, mw, "session-2", tools)+ reply_text = await _run_turn(agent, UserMsg("alice", user_msg_2))+ print(f"\n[assistant] {reply_text}")+ finally:+ # The middleware owns the embedded ReMe app it built, so a single+ # close() tears it down — ReMe's background jobs / thread pool+ # shut down cleanly. (AgentScope doesn't manage middleware+ # lifecycle, so this must be explicit.)+ await mw.close()+++if __name__ == "__main__":+ asyncio.run(main())diff --git a/pyproject.toml b/pyproject.tomlindex c5bbe15c7..fc6a72391 100644--- a/pyproject.toml+++ b/pyproject.toml@@ -101,6 +101,8 @@ s3 = [# wouldn't crash but the 2-tier add fallback degenerates into a# wasted LLM call.mem0 = ["mem0ai>=2.0.0"]+# Required by `agentscope.middleware._longterm_memory.ReMeMiddleware`.+reme = ["reme-ai>=0.4.0.6"]# ------------ Full ------------full = ["agentscope[models]",@@ -112,6 +114,7 @@ full = ["agentscope[milvuslite]","agentscope[s3]","agentscope[mem0]",+ "agentscope[reme]",]# ------------ Development ------------diff --git a/src/agentscope/middleware/__init__.py b/src/agentscope/middleware/__init__.pyindex 38f888648..822b56c43 100644--- a/src/agentscope/middleware/__init__.py+++ b/src/agentscope/middleware/__init__.py@@ -4,7 +4,11 @@from ._base import MiddlewareBasefrom ._rag import RAGMiddlewarefrom ._budget import ReplyBudgetControlMiddleware-from ._longterm_memory import AgenticMemoryMiddleware, Mem0Middleware+from ._longterm_memory import (+ AgenticMemoryMiddleware,+ Mem0Middleware,+ ReMeMiddleware,+)from ._tracing import TracingMiddlewarefrom ._tts_middleware import TTSMiddleware@@ -12,6 +16,7 @@ __all__ = ["MiddlewareBase","AgenticMemoryMiddleware","Mem0Middleware",+ "ReMeMiddleware","RAGMiddleware","TracingMiddleware","ReplyBudgetControlMiddleware",diff --git a/src/agentscope/middleware/_longterm_memory/__init__.py b/src/agentscope/middleware/_longterm_memory/__init__.pyindex f59668850..ca2fd3d6b 100644--- a/src/agentscope/middleware/_longterm_memory/__init__.py+++ b/src/agentscope/middleware/_longterm_memory/__init__.py@@ -3,5 +3,10 @@from ._agentic_memory import AgenticMemoryMiddlewarefrom ._mem0 import Mem0Middleware+from ._reme import ReMeMiddleware-__all__ = ["AgenticMemoryMiddleware", "Mem0Middleware"]+__all__ = [+ "AgenticMemoryMiddleware",+ "Mem0Middleware",+ "ReMeMiddleware",+]diff --git a/src/agentscope/middleware/_longterm_memory/_reme/__init__.py b/src/agentscope/middleware/_longterm_memory/_reme/__init__.pynew file mode 100644index 000000000..ece19427c--- /dev/null+++ b/src/agentscope/middleware/_longterm_memory/_reme/__init__.py@@ -0,0 +1,16 @@+# -*- coding: utf-8 -*-+"""ReMe-backed long-term memory middleware for AgentScope.++`ReMe <https://github.com/agentscope-ai/ReMe>`_ (``reme-ai``) is a+file-based memory toolkit built on AgentScope. This package embeds the+ReMe application in-process and exposes:++- :class:`ReMeMiddleware` — AgentScope middleware wiring an agent to an+ embedded ``reme.ReMe`` app (holds the app directly, mirroring how+ :class:`Mem0Middleware` holds a native ``mem0`` client).+"""+from ._middleware import ReMeMiddleware++__all__ = [+ "ReMeMiddleware",+]diff --git a/src/agentscope/middleware/_longterm_memory/_reme/_middleware.py b/src/agentscope/middleware/_longterm_memory/_reme/_middleware.pynew file mode 100644index 000000000..e59ead4d4--- /dev/null+++ b/src/agentscope/middleware/_longterm_memory/_reme/_middleware.py@@ -0,0 +1,564 @@+# -*- coding: utf-8 -*-+"""ReMe-backed long-term memory middleware for AgentScope agents.++`ReMe <https://github.com/agentscope-ai/ReMe>`_ is a file-based memory+toolkit built on AgentScope. This middleware **embeds the ReMe+application in-process** (no separate service to run); a chat model for+ReMe's LLM-backed jobs is configured once at construction.++ReMe records memory by **listening to the conversation through the+``on_reply`` hook** — after every reply the new exchange is written back+via ReMe's ``auto_memory`` job, in *all* modes. The agent never writes+memory itself; there is no manual add tool. The ``mode`` parameter only+controls **retrieval**:++- ``"static_control"`` — search ReMe when a reply starts and inject the+ retrieved memories into context before a later reasoning step (plus the+ automatic write-back). Retrieval runs concurrently with the reply, so+ injection is best-effort: a single-shot reply may finish first.+- ``"agent_control"`` — expose a ``memory_search`` tool the agent calls+ on demand (plus the automatic write-back); no auto-retrieval.+- ``"both"`` — auto-retrieve/inject *and* expose ``memory_search``.++ReMe scopes writes by ``session_id``, which is read from+``agent.state.session_id`` at hook time (not configured on the+middleware), so it always matches the agent's own session; search runs+over the whole workspace.+"""+from __future__ import annotations++import asyncio+from typing import (+ Any,+ AsyncGenerator,+ Callable,+ Literal,+ TYPE_CHECKING,+)++from pydantic import BaseModel, Field++from ..._base import MiddlewareBase+from ...._logging import logger+from ....embedding import EmbeddingModelBase+from ....message import AssistantMsg, HintBlock, Msg+from ....model import ChatModelBase+from ._tools import _build_memory_tools+from ._utils import _extract_memory_texts, _extract_query_text++if TYPE_CHECKING:+ from ....agent import Agent+ from ....tool import ToolBase+++# Jobs exposed by the ReMe application that this middleware drives.+_SEARCH_JOB = "search"+_AUTO_MEMORY_JOB = "auto_memory"++# ReMe component coordinates for the default chat-model / embedding+# backends. ReMe starts both eagerly at ``start()`` (the embedding+# component is wired in even when the default file store searches+# keyword-only), so an injected model bypasses ReMe building its own+# from credentials — the same escape hatch for both components.+_AS_LLM_COMPONENT = "as_llm"+_AS_EMBEDDING_COMPONENT = "as_embedding"+_AS_DEFAULT = "default"++# Header rendered above retrieved memories injected into context.+_MEMORY_MSG_NAME = "memory"+_MEMORY_SECTION_HEADER = "## Relevant memories from past conversations"+_MEMORY_SECTION_INTRO = (+ "The following memories about the user may be relevant. "+ "Use them only if they are pertinent to the current request."+)++# Appended to the system prompt to advertise the search tool to the LLM.+_TOOL_INSTRUCTIONS = (+ "## Long-term memory\n\n"+ "You have a `memory_search` tool available. Use it whenever the "+ "current conversation may depend on a durable fact from a past "+ "session (a preference, a name, a prior decision). Recording memory "+ "is handled automatically; there is no add tool."+)+++class ReMeMiddleware(MiddlewareBase):+ """AgentScope middleware that adds long-term memory backed by+ `ReMe <https://github.com/agentscope-ai/ReMe>`_.++ ReMe is embedded **in-process** (no separate service): the middleware+ instantiates a :class:`reme.ReMe` application whose LLM-backed jobs use+ the ``chat_model`` configured at construction. The app is built and+ owned by the middleware — pass ``workspace_dir`` / ``config`` (and+ optionally a ``Parameters`` with ``chat_model`` / ``embedding_model``)+ and it is created lazily on first use. When ``chat_model`` is omitted,+ ReMe uses the LLM from its own config/credentials. Providing an+ ``embedding_model`` enables ReMe's vector store; otherwise search stays+ keyword-only.++ The model is fixed at construction (never taken from an agent), so the+ embedded app's single LLM is well-defined even when one middleware+ instance is shared across several agents. Per-conversation state — the+ ReMe ``session_id`` — is instead read live from each agent at hook+ time and never stored, keeping shared use isolated. Background+ retrieval tasks are likewise tracked per ``session_id`` so concurrent+ replies in different sessions never clobber each other's in-flight+ search.++ AgentScope middleware has no framework-managed lifecycle, so the app+ is built once and started lazily on first use (idempotent). Call+ :meth:`close` for explicit teardown of the embedded app.++ Example::++ from agentscope.middleware import ReMeMiddleware+ from agentscope.tool import Toolkit++ mw = ReMeMiddleware(+ workspace_dir=".reme",+ parameters=ReMeMiddleware.Parameters(mode="both"),+ )+ agent = Agent(+ ...,+ toolkit=Toolkit(tools=await mw.list_tools()),+ middlewares=[mw],+ )+ """++ class Parameters(BaseModel):+ """User-tunable ReMe memory parameters.++ The agent service parses this schema to render a configuration+ form. Structural wiring (``workspace_dir`` / ``config``) stays on+ the constructor.+ """++ model_config = {"arbitrary_types_allowed": True}++ chat_model: ChatModelBase | None = Field(+ default=None,+ title="Chat Model",+ description=(+ "AgentScope chat model injected into ReMe's default LLM "+ "component, fixed for the lifetime of the embedded app. "+ "When `None`, ReMe uses the LLM from its own "+ "config/credentials. Needed for `auto_memory` write-back."+ ),+ )++ embedding_model: EmbeddingModelBase | None = Field(+ default=None,+ title="Embedding Model",+ description=(+ "AgentScope embedding model injected into ReMe's default "+ "embedding component, fixed for the lifetime of the embedded "+ "app. ReMe starts this component eagerly (it is wired into "+ "the file store even when search is keyword-only), so "+ "injecting a model bypasses ReMe building its own from "+ "credentials. When `None`, ReMe uses the embedding backend "+ "from its own config/credentials."+ ),+ )++ mode: Literal["static_control", "agent_control", "both"] = Field(+ default="both",+ title="Retrieval Mode",+ description=(+ "How the agent retrieves from ReMe (write-back runs "+ "automatically in every mode). `static_control`: search and "+ "inject before each reply, no tool. `agent_control`: expose "+ "the `memory_search` tool, no auto-retrieval. `both`: "+ "auto-retrieve/inject and expose the tool."+ ),+ )++ top_k: int = Field(+ default=5,+ title="Top K",+ description=(+ "Max number of memories retrieved per search, and the "+ "default `limit` advertised by the `memory_search` tool."+ ),+ )++ def __init__(+ self,+ *,+ workspace_dir: str = ".reme",+ config: str = "default",+ parameters: Parameters | None = None,+ ) -> None:+ """Initialize the ReMe middleware.++ The ReMe ``session_id`` (which scopes write-back memory cards) is+ **not** taken here — it is read from ``agent.state.session_id`` at+ hook time (every agent has one; ``AgentState`` generates it),+ mirroring :class:`TracingMiddleware`. To pin a resumable session,+ set the id on the agent (``Agent(state=AgentState(session_id=...))``).++ Args:+ workspace_dir (`str`, optional):+ ReMe workspace (vault) directory for memory cards and+ indexes. Defaults to ``".reme"``.+ config (`str`, optional):+ ReMe config name or path. Defaults to ``"default"``+ (ReMe's bundled ``default.yaml``).+ parameters (`ReMeMiddleware.Parameters | None`, optional):+ User-tunable parameters (``chat_model`` / ``embedding_model``+ / ``mode`` / ``top_k``) whose schema the agent service+ renders as a configuration form. When ``None``, defaults are+ used. Providing an ``embedding_model`` also enables ReMe's+ vector store (otherwise search is keyword-only).+ """+ # Embedded ReMe application state. The app is built lazily and+ # started once (idempotent guards), since middleware has no+ # framework-managed lifecycle. The middleware always owns the app+ # it builds, so :meth:`close` tears it down.+ self._app: Any | None = None+ self._started = False+ self._workspace_dir = workspace_dir+ self._config = config+ self._parameters = parameters or self.Parameters()+ # In-flight background retrieval per session (started in ``on_reply``,+ # consumed/injected in ``on_reasoning``, cleaned up in ``on_reply``'s+ # finally). Keyed by ``session_id`` so one middleware shared across+ # agents keeps each session's retrieval isolated — a concurrent reply+ # in another session never clobbers this one's task.+ self._retrieval_tasks: dict[Any, asyncio.Task] = {}++ # ==================================================================+ # Embedded ReMe application lifecycle+ # ==================================================================+ def _build_app(self) -> Any:+ """Lazily build the embedded :class:`reme.ReMe` application.++ Raises:+ ImportError:+ If ``reme-ai`` is not installed.+ """+ try:+ from reme import ReMe+ from reme.config import resolve_app_config+ except ImportError as e: # pragma: no cover - import guard+ raise ImportError(+ "ReMeMiddleware requires the `reme-ai` package. Install "+ 'it with `pip install "agentscope[reme]"` (or '+ "`pip install reme-ai`).",+ ) from e++ app_kwargs: dict[str, Any] = {+ "config": self._config,+ "workspace_dir": self._workspace_dir,+ "enable_logo": False,+ "log_to_console": False,+ }+ # An embedding model turns on ReMe's vector store: the bundled+ # ``default`` config ships it off (BM25 keyword search only), so we+ # wire the file store to the default embedding store when — and+ # only when — a model is available to build the vectors.+ if self._parameters.embedding_model is not None:+ app_kwargs["components"] = {+ "file_store": {"default": {"embedding_store": "default"}},+ }+ app_config = resolve_app_config(**app_kwargs)+ return ReMe(**app_config)++ async def _ensure_started(self) -> None:+ """Build (if needed) and start the embedded app (idempotent).++ The configured ``chat_model`` / ``embedding_model`` are injected+ into ReMe's default LLM and embedding components **before** the+ one-time ``start()`` (ReMe's ``BaseAsLLM._start`` /+ ``BaseAsEmbedding._start`` skip building a model from credentials+ when ``model`` is already set). Both are fixed at construction —+ never taken from an agent — so the embedded app (which has a+ single LLM and a single embedding component) has one well-defined+ model each regardless of how many agents share this middleware.+ When either is ``None``, ReMe falls back to the backend configured+ in its own config/credentials.+ """+ if self._app is None:+ self._app = self._build_app()+ if not self._started:+ if self._parameters.chat_model is not None:+ await self._app.update_component(+ _AS_LLM_COMPONENT,+ _AS_DEFAULT,+ model=self._parameters.chat_model,+ )+ if self._parameters.embedding_model is not None:+ await self._app.update_component(+ _AS_EMBEDDING_COMPONENT,+ _AS_DEFAULT,+ model=self._parameters.embedding_model,+ )+ await self._app.start()+ self._started = True++ async def close(self) -> None:+ """Close the embedded ReMe app.++ AgentScope does not manage middleware lifecycle, so call this+ explicitly for clean teardown (e.g. on application shutdown).+ """+ if self._app is not None and self._started:+ await self._app.close()+ self._started = False++ @staticmethod+ def _session_id_of(agent: "Agent") -> str | None:+ """Read the ReMe ``session_id`` live from the agent.++ ReMe scopes write-back memory cards by ``session_id``. It is read+ from ``agent.state.session_id`` at hook time and threaded through+ per call — **never** stored on the middleware — so a single+ instance shared across agents keeps each conversation's writes+ isolated. Mirrors how :class:`TracingMiddleware` sources the+ session from the agent rather than from middleware config.+ """+ return getattr(getattr(agent, "state", None), "session_id", None)++ # ------------------------------------------------------------------+ # Hook: on_reply+ # ------------------------------------------------------------------+ async def on_reply(+ self,+ agent: "Agent",+ input_kwargs: dict,+ next_handler: Callable[..., AsyncGenerator],+ ) -> AsyncGenerator:+ session_id = self._session_id_of(agent)++ # Kick off retrieval (static_control / both only) concurrently with+ # the reply. It runs in the background while the agent ingests input+ # and starts reasoning; ``on_reasoning`` injects the result once the+ # task finishes. Write the new exchange back afterwards in every mode.+ inputs = input_kwargs.get("inputs")+ query_text = _extract_query_text(inputs)++ # Discard any stale task left for this session (a previous turn that+ # never reached its finally is unexpected, but never leak one).+ stale = self._retrieval_tasks.pop(session_id, None)+ if stale is not None and not stale.done():+ stale.cancel()+ if self._parameters.mode != "agent_control" and query_text:+ self._retrieval_tasks[session_id] = asyncio.create_task(+ self._search(query_text),+ )++ # Snapshot the context BEFORE the turn so the write-back persists+ # only this turn's *increment*. ReMe's ``auto_memory`` consumes the+ # incremental exchange, whereas ``agent.state.context`` is the full+ # accumulated history — so we diff by message id (below) rather than+ # sending the whole context, which would re-feed every prior turn.+ # Taking the increment (not just the final message) still captures+ # every step of the turn — user input, each assistant step, and+ # every tool call / tool result — which the agent records on+ # ``state.context`` via ``_save_to_context`` but does not all yield+ # on the stream (only the final answer is yielded).+ pre_ids = {m.id for m in agent.state.context if isinstance(m, Msg)}++ try:+ async for item in next_handler(**input_kwargs):+ yield item+ finally:+ # Retrieval may still be running (or its hint may never have been+ # injected — e.g. a single-shot reply that finished before the+ # task did). Consume this session's task so none is orphaned.+ task = self._retrieval_tasks.pop(session_id, None)+ if task is not None and not task.done():+ task.cancel()+ if task is not None:+ try:+ await task+ except (asyncio.CancelledError, Exception): # noqa: BLE001+ pass+ # This turn's new messages only: everything now present that+ # was not before, minus any memory hint we injected (matched by+ # its reserved name, since injection happens in ``on_reasoning``).+ increment = [+ m+ for m in agent.state.context+ if isinstance(m, Msg)+ and m.id not in pre_ids+ and getattr(m, "name", None) != _MEMORY_MSG_NAME+ ]+ # Only persist a real exchange: a genuine user turn plus at+ # least one non-empty assistant message produced this turn.+ if query_text and any(+ m.role == "assistant" and m.get_text_content()+ for m in increment+ ):+ await self._write_back(increment, session_id)++ # ------------------------------------------------------------------+ # Hook: on_reasoning (inject retrieved memories once ready)+ # ------------------------------------------------------------------+ async def on_reasoning(+ self,+ agent: "Agent",+ input_kwargs: dict,+ next_handler: Callable[..., AsyncGenerator],+ ) -> AsyncGenerator:+ """Inject background-retrieved memories before a reasoning step.++ The search started in :meth:`on_reply` runs concurrently; this hook+ polls it before each reasoning step and, once it is finished, appends+ the retrieved memories to the agent's context so the *next* model+ call sees them. This is best-effort: a single-shot reply (one model+ call) may finish before retrieval does, in which case the hint is+ skipped for that turn — the same trade-off as+ :class:`AgenticMemoryMiddleware`.+ """+ session_id = self._session_id_of(agent)+ task = self._retrieval_tasks.get(session_id)+ if task is not None and task.done():+ self._retrieval_tasks.pop(session_id, None)+ try:+ memories = task.result()+ except (asyncio.CancelledError, Exception) as e: # noqa: BLE001+ memories = []+ logger.warning("ReMe search failed: %s", e)+ if memories:+ agent.state.context.append(+ self._build_memory_message(memories),+ )++ async for event in next_handler(**input_kwargs):+ yield event++ # ------------------------------------------------------------------+ # Hook: on_system_prompt (advertise the search tool to the LLM)+ # ------------------------------------------------------------------+ async def on_system_prompt(+ self,+ agent: "Agent",+ current_prompt: str,+ ) -> str:+ """Append search-tool instructions to the system prompt.++ Args:+ agent (`Agent`):+ The agent whose system prompt is being transformed.+ current_prompt (`str`):+ The system prompt produced by previous middleware.++ Returns:+ `str`:+ The unchanged prompt in static-control mode, otherwise the+ prompt with the ``memory_search`` nudge appended.+ """+ if self._parameters.mode == "static_control":+ return current_prompt+ return f"{current_prompt}\n\n{_TOOL_INSTRUCTIONS}"++ async def list_tools(self) -> list["ToolBase"]:+ """List memory tools provided by this middleware.++ Returns:+ `list[ToolBase]`:+ The ``memory_search`` tool in agent-control modes+ (``"agent_control"`` / ``"both"``), otherwise an empty+ list. There is no add tool — writing is automatic.+ """+ if self._parameters.mode == "static_control":+ return []+ return _build_memory_tools(self)++ # ==================================================================+ # ReMe job helpers (shared by hooks and tools)+ # ==================================================================+ async def _run_job(self, name: str, **kwargs: Any) -> Any:+ """Start the embedded app (if needed) and run a ReMe job.++ Raises:+ RuntimeError:+ If ReMe reports ``success=False``.+ """+ await self._ensure_started()+ assert self._app is not None+ response = await self._app.run_job(name, **kwargs)+ if getattr(response, "success", True) is False:+ raise RuntimeError(+ f"ReMe {name!r} failed: {getattr(response, 'answer', '')}",+ )+ return response++ async def _search(+ self,+ query: str,+ *,+ limit: int | None = None,+ ) -> list[str]:+ """Search ReMe and return the retrieved memory texts."""+ response = await self._run_job(+ _SEARCH_JOB,+ query=query,+ limit=self._parameters.top_k if limit is None else limit,+ )+ return _extract_memory_texts(getattr(response, "metadata", {}))++ async def _write_back(+ self,+ messages: list[Msg],+ session_id: str | None,+ ) -> None:+ """Persist a completed conversation increment to ReMe.++ ``messages`` is the full slice this turn appended to the agent's+ context — the user input, every assistant step, and every tool+ call / tool result — so ReMe's ``auto_memory`` extraction sees the+ whole exchange, not just the final answer.++ ``session_id`` is passed in per call (read live from the agent),+ never stored, so a shared middleware keeps conversations isolated.+ Skipped (with a warning) when no ``session_id`` is available;+ failures are logged rather than propagated so a write never blocks+ the reply.+ """+ if not session_id:+ logger.warning(+ "ReMe write skipped: no session_id captured from the agent.",+ )+ return+ try:+ await self._run_job(+ _AUTO_MEMORY_JOB,+ messages=[m.model_dump(mode="json") for m in messages],+ session_id=session_id,+ )+ except Exception as e: # noqa: BLE001+ logger.warning(+ "ReMe auto_memory failed for session_id=%s: %s",+ session_id,+ e,+ )++ # ==================================================================+ # Helpers+ # ==================================================================+ @staticmethod+ def _build_memory_message(memories: list[str]) -> Msg:+ """Format retrieved ``memories`` as a synthetic hint message.++ The context entry uses an assistant-role ``Msg`` container because+ user messages cannot carry ``HintBlock`` content. Formatters convert+ the ``HintBlock`` itself into a user message before the model call.++ Args:+ memories (`list[str]`):+ Retrieved memory texts to expose to the model.+ Returns:+ `Msg`:+ An assistant-role message containing one ``HintBlock``.+ """+ bullets = "\n".join(f"- {m}" for m in memories)+ content = (+ f"{_MEMORY_SECTION_HEADER}\n"+ f"{_MEMORY_SECTION_INTRO}\n"+ f"{bullets}"+ )+ return AssistantMsg(+ name=_MEMORY_MSG_NAME,+ content=[HintBlock(hint=content)],+ )diff --git a/src/agentscope/middleware/_longterm_memory/_reme/_tools.py b/src/agentscope/middleware/_longterm_memory/_reme/_tools.pynew file mode 100644index 000000000..465af8baa--- /dev/null+++ b/src/agentscope/middleware/_longterm_memory/_reme/_tools.py@@ -0,0 +1,182 @@+# -*- coding: utf-8 -*-+# pylint: disable=protected-access+"""Agent-control tool exposed by the ReMe middleware.++The single ``memory_search`` tool is listed by :class:`ReMeMiddleware`+when ``mode`` is ``"agent_control"`` or ``"both"``. The tool drives+ReMe's ``search`` action through the embedded ReMe app held on the+middleware.++Unlike the mem0 middleware (which also exposes an ``add_memory`` tool),+ReMe has **no manual add tool**: it records memory through its+``auto_memory`` job — an LLM extraction over the *conversation* — which+the middleware runs automatically on the reply path (write-back). So the+agent-facing surface is search-only.+"""+from __future__ import annotations++from typing import Any, TYPE_CHECKING++from ....message import TextBlock, ToolResultState+from ....permission import PermissionBehavior, PermissionDecision+from ....tool import ToolBase, ToolChunk++if TYPE_CHECKING:+ from ._middleware import ReMeMiddleware+++class _ReMeMemoryToolBase(ToolBase):+ """Base class for ReMe tools that auto-allow themselves.++ Middleware-provided memory tools are part of the agent's standard+ capabilities — prompting on every call would defeat the point.+ """++ is_external_tool: bool = False+ is_state_injected: bool = False+ is_mcp: bool = False+ mcp_name: str | None = None++ def __init__(+ self,+ mw: "ReMeMiddleware",+ ) -> None:+ """Bind the tool to its owning middleware.++ Args:+ mw (`ReMeMiddleware`):+ The middleware whose embedded ReMe app and parameters this+ tool drives.+ """+ self._mw = mw++ async def check_permissions(+ self,+ *_args: Any,+ **_kwargs: Any,+ ) -> PermissionDecision:+ """Auto-allow the call without prompting.++ Middleware-provided memory tools are part of the agent's standard+ capabilities, so they never require user confirmation.++ Returns:+ `PermissionDecision`:+ An ``ALLOW`` decision.+ """+ return PermissionDecision(+ behavior=PermissionBehavior.ALLOW,+ message="auto-allowed: ReMe long-term memory tool",+ )+++class _MemorySearchTool(_ReMeMemoryToolBase):+ """Agent-callable ReMe search tool.++ The advertised ``limit`` default is the middleware's ``top_k`` (set+ per instance in :meth:`__init__`), so configuring ``top_k`` on the+ middleware also governs how many memories this tool retrieves when the+ agent omits ``limit``.+ """++ name: str = "memory_search"+ description: str = (+ "Retrieve memories from past conversations relevant to a query."+ )+ is_concurrency_safe: bool = True+ is_read_only: bool = True++ def __init__(+ self,+ mw: "ReMeMiddleware",+ ) -> None:+ """Bind the tool to ``mw`` and build its per-instance schema.++ The advertised ``limit`` default is read from the middleware's+ ``top_k`` here (rather than a hardcoded constant), so configuring+ ``top_k`` on the middleware also governs the tool's default.++ Args:+ mw (`ReMeMiddleware`):+ The middleware whose embedded ReMe app and ``top_k`` this+ search tool uses.+ """+ super().__init__(mw)+ # Per-instance schema so the default ``limit`` reflects this+ # middleware's ``top_k`` rather than a hardcoded constant.+ self.input_schema: dict[str, Any] = {+ "type": "object",+ "properties": {+ "query": {+ "type": "string",+ "description": (+ "What to retrieve from memory — for example a "+ "person's name, a preference, or a past decision."+ ),+ },+ "limit": {+ "type": "integer",+ "description": "Maximum number of memories to retrieve.",+ "default": mw._parameters.top_k,+ },+ },+ "required": ["query"],+ }++ async def __call__(+ self,+ query: str,+ limit: int | None = None,+ ) -> ToolChunk:+ """Retrieve memory relevant to ``query``.++ Args:+ query (str):+ What to retrieve from the ReMe workspace (for example a+ person's name, a preference, or a past decision).+ limit (int | None):+ The maximum number of memories to retrieve. When omitted,+ falls back to the middleware's ``top_k``.+ """+ if not query:+ return _text_chunk("(no query supplied — nothing to search)")++ try:+ memories = await self._mw._search(query, limit=limit)+ except Exception as e: # noqa: BLE001+ return _error_chunk(f"Error retrieving memory: {e}")++ if not memories:+ return _text_chunk("(no relevant memories found)")+ return _text_chunk("\n".join(f"- {m}" for m in memories))+++def _build_memory_tools(+ mw: "ReMeMiddleware",+) -> list[ToolBase]:+ """Return the ``memory_search`` tool bound to ``mw``.++ ReMe's agent-facing surface is search-only — writing is handled+ automatically by the middleware's ``auto_memory`` write-back, not a+ manual tool.+ """+ return [+ _MemorySearchTool(mw),+ ]+++def _text_chunk(message: str) -> ToolChunk:+ """Wrap a text message as a normal tool chunk."""+ return ToolChunk(+ content=[TextBlock(type="text", text=message)],+ )+++def _error_chunk(message: str) -> ToolChunk:+ """Wrap an error message as a ``ToolChunk(state=ERROR)`` so the+ toolkit aggregates it as a failed tool call — the agent sees the+ message and can decide whether to retry or move on."""+ return ToolChunk(+ content=[TextBlock(type="text", text=message)],+ state=ToolResultState.ERROR,+ )diff --git a/src/agentscope/middleware/_longterm_memory/_reme/_utils.py b/src/agentscope/middleware/_longterm_memory/_reme/_utils.pynew file mode 100644index 000000000..65f0c8276--- /dev/null+++ b/src/agentscope/middleware/_longterm_memory/_reme/_utils.py@@ -0,0 +1,104 @@+# -*- coding: utf-8 -*-+"""Pure helper functions for the ReMe middleware.++These are stateless adapters that translate between AgentScope and ReMe+data shapes. Keeping them out of the middleware class makes them trivial+to unit-test in isolation.+"""+from __future__ import annotations++from typing import Any++from ....event import ExternalExecutionResultEvent, UserConfirmResultEvent+from ....message import Msg+++def _extract_query_text(inputs: Any) -> str | None:+ """Pull a single text query out of the agent inputs.++ Returns ``None`` for resumption events or empty/non-user inputs,+ in which case the middleware skips both retrieval and write-back.++ Args:+ inputs (`Any`):+ The unified ``on_reply`` inputs — a ``Msg``, a list of+ ``Msg``, a HITL resumption event, or ``None``.++ Returns:+ `str | None`:+ The joined text of all user messages, or ``None`` when there+ is nothing to search/write.+ """+ if inputs is None:+ return None+ if isinstance(+ inputs,+ (ExternalExecutionResultEvent, UserConfirmResultEvent),+ ):+ return None++ msgs = inputs if isinstance(inputs, list) else [inputs]+ texts: list[str] = []+ for m in msgs:+ if not isinstance(m, Msg) or m.role != "user":+ continue+ text = m.get_text_content()+ if text:+ texts.append(text)+ return "\n".join(texts) if texts else None+++def _extract_memory_texts(raw: Any) -> list[str]:+ """Flatten a ReMe ``search`` response into a list of memory strings.++ ReMe's ``search`` returns a ``Response`` envelope whose+ ``metadata["results"]`` is a list of file chunks. This helper+ tolerates the common shapes:++ - ``{"metadata": {"results": [{"text": str, "path": str, ...}, ...]}}``+ (the standard ``search`` response)+ - ``{"results": [{"text": str, ...}, ...]}`` (already-unwrapped)+ - ``[{"text": str, ...}, ...]`` (plain list of chunks)+ - ``[str, ...]`` / ``{"results": [str, ...]}`` (defensive fallback)++ Each chunk's text is taken from ``text`` (ReMe's ``FileChunk.text``),+ falling back to ``memory`` / ``content`` for forward compatibility.++ Args:+ raw (`Any`):+ The raw object returned by ReMe's ``search`` job (e.g.+ ``ReMe.run_job("search", ...)``) or the decoded ReMe response+ envelope.++ Returns:+ `list[str]`:+ Retrieved memory texts, in response order.+ """+ if raw is None:+ return []++ results: Any = raw+ if isinstance(raw, dict):+ # Unwrap one level of ``metadata`` if present, then ``results``.+ if (+ isinstance(raw.get("metadata"), dict)+ and "results" in raw["metadata"]+ ):+ results = raw["metadata"]["results"]+ else:+ results = raw.get("results", raw)++ if not isinstance(results, list):+ return []++ out: list[str] = []+ for item in results:+ if isinstance(item, str):+ out.append(item)+ elif isinstance(item, dict):+ text = (+ item.get("text") or item.get("memory") or item.get("content")+ )+ if text:+ out.append(str(text))+ return outdiff --git a/tests/reme_middleware_test.py b/tests/reme_middleware_test.pynew file mode 100644index 000000000..ad8044e78--- /dev/null+++ b/tests/reme_middleware_test.py@@ -0,0 +1,1242 @@+# -*- coding: utf-8 -*-+# pylint: disable=protected-access,unused-argument+"""Unit tests for ReMeMiddleware.++The embedded ReMe app is mocked — we only exercise the AgentScope hook+wiring (retrieve-before / write-after, system-prompt injection,+list_tools exposure) and the small adapters that translate between+AgentScope and ReMe. No real ReMe application is built.++``protected-access`` is disabled because tests legitimately reach into+middleware internals (``mw._app``, ``mw._search``, ``mw._session_id_of``)+to inspect what the public API just did.+"""+import sys+import types+import asyncio+from unittest import mock+from unittest.async_case import IsolatedAsyncioTestCase+from typing import Any++from utils import MockModel++from agentscope.agent import Agent+from agentscope.event import (+ ExternalExecutionResultEvent,+ UserConfirmResultEvent,+)+from agentscope.message import (+ HintBlock,+ Msg,+ TextBlock,+ ToolCallBlock,+ UserMsg,+)+from agentscope.embedding import EmbeddingModelBase+from agentscope.middleware import ReMeMiddleware+from agentscope.middleware._longterm_memory._reme._utils import (+ _extract_memory_texts,+ _extract_query_text,+)+from agentscope.model import ChatResponse+from agentscope.permission import (+ PermissionBehavior,+ PermissionContext,+ PermissionDecision,+)+from agentscope.tool import Toolkit, ToolBase, ToolChunk+++# ----------------------------------------------------------------------+# Test helpers+# ----------------------------------------------------------------------+++class RecordingMockModel(MockModel):+ """MockModel that captures the ``messages`` of every _call_api call."""++ def __init__(self, *args: Any, **kwargs: Any) -> None:+ """Initialize the recording mock model."""+ super().__init__(*args, **kwargs)+ self.calls: list[list[Msg]] = []++ async def _call_api(+ self,+ *args: Any,+ **kwargs: Any,+ ) -> Any:+ """Record messages before delegating to MockModel."""+ messages = kwargs.get("messages")+ if messages is None and len(args) >= 2:+ messages = args[1]+ self.calls.append(list(messages or []))+ return await super()._call_api(*args, **kwargs)++ @property+ def last_call_messages(self) -> list[Msg]:+ """Return the most recent model-call messages."""+ return self.calls[-1]+++class _FakeEmbedding(EmbeddingModelBase):+ """Minimal ``EmbeddingModelBase`` instance for tests.++ ``ReMeMiddleware.Parameters.embedding_model`` is validated by pydantic+ (``arbitrary_types_allowed`` still isinstance-checks), so tests need a+ real subclass rather than a bare sentinel. Its API is never called —+ the middleware only checks presence and passes it through to ReMe.+ """++ def __init__(self) -> None:+ """Skip the heavy base init; nothing here is exercised."""++ async def _call_api( # pragma: no cover - never invoked in tests+ self,+ inputs: list[Any],+ **kwargs: Any,+ ) -> Any:+ """Unused: no test drives an actual embedding call."""+ raise NotImplementedError+++class _FakeResponse:+ """Minimal stand-in for ReMe's ``Response`` (answer/success/metadata)."""++ def __init__(+ self,+ *,+ answer: str = "",+ success: bool = True,+ metadata: dict | None = None,+ ) -> None:+ """Initialize the fake response."""+ self.answer = answer+ self.success = success+ self.metadata = metadata or {}+++class _FakeReMeApp:+ """Stands in for an embedded :class:`reme.ReMe` application.++ Mirrors the surface :class:`ReMeMiddleware` drives directly (now that+ there is no client wrapper): ``start`` / ``close`` lifecycle,+ ``update_component`` (model injection), ``is_started``, and+ ``run_job(name, **kwargs) -> Response``. Every job call is recorded;+ ``search_calls`` / ``auto_memory_calls`` re-expose them in the+ middleware's own terms for assertions.+ """++ def __init__(self, search_return: Any = None) -> None:+ """Initialize the fake ReMe app."""+ self.search_return = list(search_return) if search_return else []+ self.run_job_calls: list[dict] = []+ self.injected_models: list[Any] = []+ self.injected_components: dict[str, Any] = {}+ self.start_count = 0+ self.closed = False+ self.is_started = False+ # Set to an exception to simulate a failing job.+ self.search_error: Exception | None = None+ self.auto_memory_error: Exception | None = None++ async def start(self) -> None:+ """Record an idempotent start."""+ self.start_count += 1+ self.is_started = True++ async def close(self) -> None:+ """Record a close."""+ self.closed = True+ self.is_started = False++ async def update_component(+ self,+ component: str,+ name: str,+ **kwargs: Any,+ ) -> None:+ """Record a model injection into a ReMe default component."""+ self.injected_models.append(kwargs.get("model"))+ self.injected_components[component] = kwargs.get("model")++ async def run_job(self, name: str, **kwargs: Any) -> _FakeResponse:+ """Dispatch a ReMe job, recording the call."""+ self.run_job_calls.append({"name": name, **kwargs})+ if name == "search":+ if self.search_error is not None:+ raise self.search_error+ results = [{"text": t} for t in self.search_return]+ return _FakeResponse(metadata={"results": results})+ if name == "auto_memory":+ if self.auto_memory_error is not None:+ raise self.auto_memory_error+ return _FakeResponse(answer="recorded", success=True)+ return _FakeResponse()++ @property+ def search_calls(self) -> list[dict]:+ """Recorded search jobs in the middleware's terms."""+ return [+ {+ "query": c.get("query"),+ "limit": c.get("limit"),+ }+ for c in self.run_job_calls+ if c["name"] == "search"+ ]++ @property+ def auto_memory_calls(self) -> list[dict]:+ """Recorded auto_memory jobs in the middleware's terms."""+ return [+ {+ "messages": c.get("messages"),+ "session_id": c.get("session_id"),+ }+ for c in self.run_job_calls+ if c["name"] == "auto_memory"+ ]++ @property+ def last_chat_model(self) -> Any:+ """The model injected into the ``as_llm`` component, if any."""+ return self.injected_components.get("as_llm")++ @property+ def last_embedding_model(self) -> Any:+ """The model injected into the ``as_embedding`` component."""+ return self.injected_components.get("as_embedding")+++def _mw(*, app: Any = None, **kwargs: Any) -> ReMeMiddleware:+ """Build a ``ReMeMiddleware`` with a fake embedded app injected.++ ``ReMeMiddleware`` owns and builds its own ``reme.ReMe`` app, so tests+ can't pass one in. Instead we construct the middleware normally and+ seed ``mw._app`` with a :class:`_FakeReMeApp` before it starts — the+ lazy ``_ensure_started`` path sees a non-``None`` app and skips the+ real build, so no ``reme-ai`` install is needed.++ User-tunable kwargs (``chat_model`` / ``embedding_model`` / ``mode`` /+ ``top_k``) are collected into a ``ReMeMiddleware.Parameters`` so tests+ can keep passing them flat; the rest go straight to the constructor.+ """+ param_keys = ("chat_model", "embedding_model", "mode", "top_k")+ param_kwargs = {k: kwargs.pop(k) for k in param_keys if k in kwargs}+ if param_kwargs:+ kwargs["parameters"] = ReMeMiddleware.Parameters(**param_kwargs)+ mw = ReMeMiddleware(**kwargs)+ mw._app = app if app is not None else _FakeReMeApp()+ return mw+++def _single_response(text: str) -> ChatResponse:+ """Build a final single-text chat response."""+ return ChatResponse(+ content=[TextBlock(type="text", text=text)],+ is_last=True,+ )+++def _echo_then_text(final_text: str, echo: str = "ping") -> list:+ """Two-step response sequence: an ``echo`` tool call, then a text answer.++ Auto-retrieval now runs as a background task started in ``on_reply`` and+ injected in ``on_reasoning`` once it finishes. A single-shot reply may+ complete before retrieval does, so tests that need to observe the+ injected memory drive a tool call first (two reasoning steps): the task+ finishes during step 1, so the hint is present before step 2's model+ call — the same pattern the AgenticMemory middleware tests use.+ """+ return [+ [+ ChatResponse(+ content=[+ ToolCallBlock(+ id="call-1",+ name="echo",+ input=f'{{"text": "{echo}"}}',+ ),+ ],+ is_last=True,+ ),+ ],+ [+ ChatResponse(+ content=[TextBlock(text=final_text)],+ is_last=True,+ ),+ ],+ ]+++class _EchoTool(ToolBase):+ """A trivial always-allowed tool used to force a multi-step turn."""++ name: str = "echo"+ description: str = "Echo the given text back."+ input_schema: dict[str, Any] = {+ "type": "object",+ "properties": {+ "text": {"type": "string", "description": "Text to echo."},+ },+ "required": ["text"],+ }+ is_concurrency_safe: bool = True+ is_read_only: bool = True+ is_external_tool: bool = False+ is_mcp: bool = False++ async def check_permissions(+ self,+ tool_input: dict[str, Any],+ context: PermissionContext,+ ) -> PermissionDecision:+ """Always allow — this is a test fixture."""+ return PermissionDecision(+ behavior=PermissionBehavior.ALLOW,+ decision_reason="test tool",+ message="test tool",+ )++ async def __call__(self, text: str, **kwargs: Any) -> ToolChunk:+ """Echo ``text`` back as the tool result."""+ return ToolChunk(content=[TextBlock(text=f"echo: {text}")])+++def _all_tool_names(toolkit: Toolkit) -> list[str]:+ """Flatten every registered tool's name across every group."""+ return [t.name for g in toolkit.tool_groups for t in g.tools]+++def _find_tool(toolkit: Toolkit, name: str) -> Any:+ """Look a tool up by name across every group on the toolkit."""+ for g in toolkit.tool_groups:+ for t in g.tools:+ if t.name == name:+ return t+ raise LookupError(f"tool {name!r} not found in any group")+++def _find_group(toolkit: Toolkit, name: str) -> Any:+ """Look a tool group up by name on the toolkit."""+ for g in toolkit.tool_groups:+ if g.name == name:+ return g+ raise LookupError(f"tool group {name!r} not found")+++def _chunk_text(chunk: Any) -> str:+ """Return the first text block from a tool chunk."""+ return chunk.content[0].text+++def _msg_text(m: Any) -> str:+ """Text of a message that may be a ``Msg`` or a serialized dict.++ The middleware serializes messages via ``Msg.model_dump(mode="json")``+ before handing them to ReMe's ``auto_memory`` job, so the fake app+ records dicts whose ``content`` is a list of typed blocks.+ """+ if hasattr(m, "get_text_content"):+ return m.get_text_content() or ""+ content = m.get("content") if isinstance(m, dict) else None+ if isinstance(content, str):+ return content+ if isinstance(content, list):+ return "\n".join(+ b.get("text", "")+ for b in content+ if isinstance(b, dict) and b.get("type") == "text"+ )+ return ""+++# ----------------------------------------------------------------------+# Unit tests for module-level helpers+# ----------------------------------------------------------------------+++class TestExtractQueryText(IsolatedAsyncioTestCase):+ """Tests for extracting the query text from incoming inputs."""++ def test_none_and_empty(self) -> None:+ """None and empty inputs should not produce a query."""+ self.assertIsNone(_extract_query_text(None))+ self.assertIsNone(_extract_query_text([]))++ def test_single_user_msg(self) -> None:+ """A single user message should become its text content."""+ msg = UserMsg("user", "hello world")+ self.assertEqual(_extract_query_text(msg), "hello world")++ def test_list_of_user_msgs_joined(self) -> None:+ """Multiple user messages should be joined by newlines."""+ msgs = [UserMsg("user", "first"), UserMsg("user", "second")]+ self.assertEqual(_extract_query_text(msgs), "first\nsecond")++ def test_resumption_events_return_none(self) -> None:+ """HITL resumption events should not trigger memory IO."""+ self.assertIsNone(+ _extract_query_text(+ UserConfirmResultEvent(+ reply_id="reply",+ confirm_results=[],+ ),+ ),+ )+ self.assertIsNone(+ _extract_query_text(+ ExternalExecutionResultEvent(+ reply_id="reply",+ execution_results=[],+ ),+ ),+ )+++class TestExtractMemoryTexts(IsolatedAsyncioTestCase):+ """Tests for normalizing ReMe search responses into text lists."""++ def test_metadata_results_file_chunks(self) -> None:+ """The standard ReMe envelope nests chunks under metadata."""+ raw = {+ "answer": "",+ "success": True,+ "metadata": {+ "results": [+ {"text": "a", "path": "daily/1.md", "score": 0.9},+ {"text": "b", "path": "daily/2.md", "score": 0.8},+ ],+ },+ }+ self.assertEqual(_extract_memory_texts(raw), ["a", "b"])++ def test_unwrapped_results(self) -> None:+ """An already-unwrapped results list should also work."""+ self.assertEqual(+ _extract_memory_texts({"results": [{"text": "only"}]}),+ ["only"],+ )++ def test_plain_list_of_dicts_and_strings(self) -> None:+ """Plain lists of chunks or strings should be supported."""+ self.assertEqual(+ _extract_memory_texts([{"memory": "m"}, "raw"]),+ ["m", "raw"],+ )++ def test_none_and_garbage(self) -> None:+ """Malformed ReMe outputs should normalize to an empty list."""+ self.assertEqual(_extract_memory_texts(None), [])+ self.assertEqual(+ _extract_memory_texts({"metadata": {"results": "nope"}}),+ [],+ )+++# ----------------------------------------------------------------------+# Constructor validation+# ----------------------------------------------------------------------+++class TestConstructorValidation(IsolatedAsyncioTestCase):+ """Tests for ReMeMiddleware constructor validation."""++ def test_unknown_mode_raises(self) -> None:+ """Unknown control modes should be rejected by the Parameters model."""+ from pydantic import ValidationError++ with self.assertRaises(ValidationError):+ ReMeMiddleware.Parameters(+ mode="garbage", # type: ignore[arg-type]+ )++ def test_session_id_not_stored_on_middleware(self) -> None:+ """session_id is read live from the agent, never stored.++ The middleware takes no ``session_id`` argument and keeps no+ ``_session_id`` attribute, so one instance shared across agents+ cannot leak one conversation's session into another's write-back.+ It is read per call from ``agent.state.session_id``.+ """+ mw = ReMeMiddleware()+ self.assertFalse(hasattr(mw, "_session_id"))++ class _State:+ session_id = "sess-xyz"++ class _Agent:+ state = _State()++ self.assertEqual(mw._session_id_of(_Agent()), "sess-xyz")+ self.assertIsNone(mw._session_id_of(object()))++ def test_embedding_model_enables_vector_store(self) -> None:+ """An ``embedding_model`` turns ReMe's vector store on at build."""+ captured: dict = {}++ def _fake_resolve(**kwargs: Any) -> dict:+ captured.update(kwargs)+ return {"_ok": True}++ fake_reme = types.ModuleType("reme")+ fake_reme.ReMe = lambda **kw: ("app", kw) # type: ignore[attr-defined]+ fake_cfg = types.ModuleType("reme.config")+ setattr(fake_cfg, "resolve_app_config", _fake_resolve)++ mw = ReMeMiddleware(+ workspace_dir="/real/ws",+ config="mycfg",+ parameters=ReMeMiddleware.Parameters(+ embedding_model=_FakeEmbedding(),+ ),+ )+ with mock.patch.dict(+ sys.modules,+ {"reme": fake_reme, "reme.config": fake_cfg},+ ):+ mw._build_app()++ self.assertEqual(+ captured["components"],+ {"file_store": {"default": {"embedding_store": "default"}}},+ )+ self.assertEqual(captured["workspace_dir"], "/real/ws")+ self.assertEqual(captured["config"], "mycfg")+ self.assertFalse(captured["enable_logo"])++ def test_no_embedding_model_keeps_keyword_only(self) -> None:+ """Without an ``embedding_model`` the vector store stays off."""+ captured: dict = {}++ def _fake_resolve(**kwargs: Any) -> dict:+ captured.update(kwargs)+ return {"_ok": True}++ fake_reme = types.ModuleType("reme")+ fake_reme.ReMe = lambda **kw: ("app", kw) # type: ignore[attr-defined]+ fake_cfg = types.ModuleType("reme.config")+ setattr(fake_cfg, "resolve_app_config", _fake_resolve)++ mw = ReMeMiddleware(workspace_dir="/real/ws")+ with mock.patch.dict(+ sys.modules,+ {"reme": fake_reme, "reme.config": fake_cfg},+ ):+ mw._build_app()++ self.assertNotIn("components", captured)+++# ----------------------------------------------------------------------+# Static-control mode (default)+# ----------------------------------------------------------------------+++class TestStaticControlMode(IsolatedAsyncioTestCase):+ """Default mode: retrieve-before / inject / write-after, no tools."""++ async def asyncSetUp(self) -> None:+ """Create a fresh recording model and empty toolkit."""+ self.model = RecordingMockModel(context_size=100_000)+ self.toolkit = Toolkit()++ def _agent(+ self,+ middleware: ReMeMiddleware,+ response_text: str = "ok",+ ) -> Agent:+ """Build a test agent using ``middleware`` and one response."""+ self.model.set_responses([_single_response(response_text)])+ return Agent(+ name="agent_under_test",+ system_prompt="base system prompt",+ model=self.model,+ toolkit=self.toolkit,+ middlewares=[middleware],+ )++ async def test_retrieve_inject_write(self) -> None:+ """Static control should search, inject, reply, then write."""+ fake = _FakeReMeApp(search_return=["alice loves coffee"])+ mw = _mw(+ app=fake,+ mode="static_control",+ )++ # A tool call gives two reasoning steps, so the background retrieval+ # finishes and its hint injects before the final model call.+ self.model.set_responses(_echo_then_text("hi alice"))+ toolkit = Toolkit(tools=[_EchoTool()])+ agent = Agent(+ name="agent_under_test",+ system_prompt="base system prompt",+ model=self.model,+ toolkit=toolkit,+ middlewares=[mw],+ )+ # session_id is sourced from the agent, not the middleware.+ agent.state.session_id = "alice-001"+ reply = await agent.reply(UserMsg("user", "remind me what I like"))++ # 1. search called with the user query, configured limit/min_score+ self.assertEqual(len(fake.search_calls), 1)+ self.assertEqual(+ fake.search_calls[0]["query"],+ "remind me what I like",+ )+ self.assertEqual(fake.search_calls[0]["limit"], 5)++ # 2. write called post-turn with the user+assistant pair, scoped+ # by session_id.+ self.assertEqual(len(fake.auto_memory_calls), 1)+ write = fake.auto_memory_calls[0]+ self.assertEqual(write["session_id"], "alice-001")+ written_texts = [_msg_text(m) for m in write["messages"]]+ self.assertIn("remind me what I like", written_texts)+ self.assertIn("hi alice", written_texts)++ # 3. system prompt unchanged — static_control adds no tool nudge.+ sys_msg = self.model.last_call_messages[0]+ self.assertEqual(sys_msg.role, "system")+ self.assertEqual(sys_msg.get_text_content(), "base system prompt")++ # 4. memory appended to the agent's persistent context as an+ # assistant-role hint note named "memory".+ memory_msgs = [+ m+ for m in agent.state.context+ if getattr(m, "name", None) == "memory"+ ]+ self.assertEqual(len(memory_msgs), 1)+ self.assertEqual(memory_msgs[0].role, "assistant")+ memory_hints = memory_msgs[0].get_content_blocks("hint")+ self.assertEqual(len(memory_hints), 1)+ self.assertIsInstance(memory_hints[0], HintBlock)+ memory_text = memory_hints[0].hint+ self.assertIn("Relevant memories", memory_text)+ self.assertIn("alice loves coffee", memory_text)+ # The model saw it on the final call (injected before step 2).+ delivered = [+ m+ for m in self.model.last_call_messages+ if getattr(m, "name", None) == "memory"+ ]+ self.assertEqual(len(delivered), 1)++ # 5. no agent-control tools registered (in any group)+ all_names = _all_tool_names(toolkit)+ self.assertNotIn("memory_search", all_names)+ self.assertNotIn("add_memory", all_names)++ self.assertEqual(reply.get_text_content(), "hi alice")++ async def test_write_back_includes_full_turn_increment(self) -> None:+ """Write-back persists the whole turn — user input, the tool-call+ step, the tool result, and the final answer — not just the last+ message, and never the injected memory note."""+ fake = _FakeReMeApp(search_return=["remembered fact"])+ mw = _mw(app=fake, mode="static_control")++ # Turn 1: the model asks for a tool call; turn 2: it answers.+ self.model.set_responses(+ [+ [+ ChatResponse(+ content=[+ ToolCallBlock(+ id="call-1",+ name="echo",+ input='{"text": "ping"}',+ ),+ ],+ is_last=True,+ ),+ ],+ [+ ChatResponse(+ content=[TextBlock(text="final answer")],+ is_last=True,+ ),+ ],+ ],+ )+ agent = Agent(+ name="agent_under_test",+ system_prompt="base system prompt",+ model=self.model,+ toolkit=Toolkit(tools=[_EchoTool()]),+ middlewares=[mw],+ )+ agent.state.session_id = "s-multi"++ await agent.reply(UserMsg("user", "use the echo tool then answer"))++ self.assertEqual(len(fake.auto_memory_calls), 1)+ written = fake.auto_memory_calls[0]["messages"]++ # The injected memory hint is NEVER written back.+ self.assertFalse(+ any(m.get("name") == "memory" for m in written),+ "the injected memory note must be excluded from write-back",+ )++ # Every step of the turn is present: user input, the assistant+ # tool call, the tool result, and the final answer.+ block_types = {+ b.get("type")+ for m in written+ for b in (m.get("content") or [])+ if isinstance(b, dict)+ }+ self.assertIn("tool_call", block_types)+ self.assertIn("tool_result", block_types)++ texts = [_msg_text(m) for m in written]+ self.assertIn("use the echo tool then answer", texts)+ self.assertIn("final answer", texts)++ async def test_write_back_is_per_turn_increment(self) -> None:+ """Each write-back carries ONLY that turn's new messages.++ ``auto_memory`` consumes the incremental exchange, while+ ``agent.state.context`` is the full accumulated history — so a+ second turn must not re-send the first turn's messages.+ """+ fake = _FakeReMeApp(search_return=[])+ mw = _mw(app=fake, mode="static_control")++ # Two sequential turns on the SAME agent (shared, growing context).+ self.model.set_responses(+ [+ _single_response("first answer"),+ _single_response("second answer"),+ ],+ )+ agent = Agent(+ name="agent_under_test",+ system_prompt="base system prompt",+ model=self.model,+ toolkit=self.toolkit,+ middlewares=[mw],+ )+ agent.state.session_id = "s-seq"++ await agent.reply(UserMsg("user", "first question"))+ await agent.reply(UserMsg("user", "second question"))++ self.assertEqual(len(fake.auto_memory_calls), 2)+ first_texts = [+ _msg_text(m) for m in fake.auto_memory_calls[0]["messages"]+ ]+ second_texts = [+ _msg_text(m) for m in fake.auto_memory_calls[1]["messages"]+ ]++ # Turn 1 wrote only turn-1 content.+ self.assertIn("first question", first_texts)+ self.assertIn("first answer", first_texts)++ # Turn 2 wrote ONLY turn-2 content — none of turn 1 leaked in,+ # even though it is still present in agent.state.context.+ self.assertIn("second question", second_texts)+ self.assertIn("second answer", second_texts)+ self.assertNotIn("first question", second_texts)+ self.assertNotIn("first answer", second_texts)++ async def test_memory_message_lands_after_user_message(self) -> None:+ """The memory note is inserted AFTER the new user input lands in the+ agent context (injected on a later reasoning step, not before)."""+ fake = _FakeReMeApp(search_return=["saved fact"])+ mw = _mw(+ app=fake,+ mode="static_control",+ )+ self.model.set_responses(_echo_then_text("answer"))+ agent = Agent(+ name="agent_under_test",+ system_prompt="base system prompt",+ model=self.model,+ toolkit=Toolkit(tools=[_EchoTool()]),+ middlewares=[mw],+ )+ await agent.reply(UserMsg("user", "tell me what you know"))++ roles_and_names = [+ (m.role, getattr(m, "name", None)) for m in agent.state.context+ ]+ user_idx = next(+ i+ for i, (r, n) in enumerate(roles_and_names)+ if r == "user" and n != "memory"+ )+ memory_idx = next(+ i for i, (_, n) in enumerate(roles_and_names) if n == "memory"+ )+ self.assertGreater(+ memory_idx,+ user_idx,+ f"memory note at {memory_idx} should come after user msg "+ f"at {user_idx}: {roles_and_names}",+ )++ async def test_no_memories_no_injection(self) -> None:+ """Empty search results should not add a memory hint message."""+ fake = _FakeReMeApp(search_return=[])+ mw = _mw(+ app=fake,+ mode="static_control",+ )++ # Tool call → two reasoning steps, so retrieval completes and the+ # injection path is exercised; with empty results it must add nothing.+ self.model.set_responses(_echo_then_text("ok"))+ agent = Agent(+ name="agent_under_test",+ system_prompt="base system prompt",+ model=self.model,+ toolkit=Toolkit(tools=[_EchoTool()]),+ middlewares=[mw],+ )+ await agent.reply(UserMsg("user", "hi"))++ msgs = self.model.last_call_messages+ self.assertEqual(msgs[0].get_text_content(), "base system prompt")+ for m in msgs:+ self.assertNotEqual(getattr(m, "name", None), "memory")+ for m in agent.state.context:+ self.assertNotEqual(getattr(m, "name", None), "memory")+ self.assertEqual(len(fake.search_calls), 1)++ async def test_search_failure_does_not_break_reply(self) -> None:+ """Search errors should be logged but not block the reply."""+ fake = _FakeReMeApp()+ fake.search_error = RuntimeError("reme down")+ mw = _mw(+ app=fake,+ mode="static_control",+ )++ agent = self._agent(mw, response_text="still works")+ reply = await agent.reply(UserMsg("user", "ping"))++ self.assertEqual(reply.get_text_content(), "still works")+ # Write still happened — a failed search must not block writes.+ self.assertEqual(len(fake.auto_memory_calls), 1)++ async def test_shared_middleware_isolates_sessions(self) -> None:+ """One middleware shared by two agents writes each agent's own+ session_id — no leakage from a stored session."""+ fake = _FakeReMeApp()+ mw = _mw(app=fake, mode="static_control")++ self.model.set_responses(+ [_single_response("r1"), _single_response("r2")],+ )+ agent_a = Agent(+ name="a",+ system_prompt="p",+ model=self.model,+ toolkit=Toolkit(),+ middlewares=[mw],+ )+ agent_a.state.session_id = "sess-a"+ agent_b = Agent(+ name="b",+ system_prompt="p",+ model=self.model,+ toolkit=Toolkit(),+ middlewares=[mw],+ )+ agent_b.state.session_id = "sess-b"++ await agent_a.reply(UserMsg("user", "hi from a"))+ await agent_b.reply(UserMsg("user", "hi from b"))++ sessions = [c["session_id"] for c in fake.auto_memory_calls]+ self.assertEqual(sessions, ["sess-a", "sess-b"])++ async def test_concurrent_sessions_isolate_retrieval_tasks(self) -> None:+ """Retrieval tasks are keyed by session_id, so two replies running+ concurrently on a shared middleware never clobber each other's+ in-flight search — each session injects its own note and no task is+ left behind."""+ fake = _FakeReMeApp(search_return=["shared fact"])+ mw = _mw(app=fake, mode="static_control")++ def _make_agent(sid: str) -> Agent:+ # Distinct model per agent: a shared response queue would be+ # consumed racily by concurrent turns.+ model = RecordingMockModel(context_size=100_000)+ model.set_responses(_echo_then_text(f"done-{sid}"))+ agent = Agent(+ name=sid,+ system_prompt="base",+ model=model,+ toolkit=Toolkit(tools=[_EchoTool()]),+ middlewares=[mw],+ )+ agent.state.session_id = sid+ return agent++ agent_a = _make_agent("sess-a")+ agent_b = _make_agent("sess-b")++ await asyncio.gather(+ agent_a.reply(UserMsg("user", "a asks")),+ agent_b.reply(UserMsg("user", "b asks")),+ )++ # Each session injected its own memory note exactly once.+ for agent in (agent_a, agent_b):+ notes = [+ m+ for m in agent.state.context+ if getattr(m, "name", None) == "memory"+ ]+ self.assertEqual(len(notes), 1, f"{agent.name} missing its note")++ # No task left behind for either session after both turns finish.+ self.assertEqual(mw._retrieval_tasks, {})++ async def test_chat_model_injected_at_start(self) -> None:+ """The configured chat_model is injected into ReMe at start."""+ explicit = RecordingMockModel(context_size=100_000)+ fake = _FakeReMeApp()+ mw = _mw(+ app=fake,+ mode="static_control",+ chat_model=explicit,+ )+ agent = self._agent(mw)+ await agent.reply(UserMsg("user", "hi"))+ self.assertIs(mw._parameters.chat_model, explicit)+ self.assertIs(fake.last_chat_model, explicit)++ async def test_no_chat_model_no_injection(self) -> None:+ """Without a chat_model the middleware injects nothing.++ The model is fixed at construction and never taken from the agent,+ so ReMe falls back to the LLM in its own config/credentials.+ """+ fake = _FakeReMeApp()+ mw = _mw(+ app=fake,+ mode="static_control",+ )+ agent = self._agent(mw)+ await agent.reply(UserMsg("user", "hi"))+ self.assertIsNone(mw._parameters.chat_model)+ self.assertEqual(fake.injected_models, [])++ async def test_embedding_model_injected_at_start(self) -> None:+ """The configured embedding_model is injected into ReMe at start.++ ReMe starts its ``as_embedding`` component eagerly; injecting a+ model bypasses ReMe building its own from credentials, mirroring+ the chat-model injection into ``as_llm``.+ """+ chat = RecordingMockModel(context_size=100_000)+ embedding = _FakeEmbedding() # only passed through to ReMe+ fake = _FakeReMeApp()+ mw = _mw(+ app=fake,+ mode="static_control",+ chat_model=chat,+ embedding_model=embedding,+ )+ agent = self._agent(mw)+ await agent.reply(UserMsg("user", "hi"))+ self.assertIs(mw._parameters.embedding_model, embedding)+ self.assertIs(fake.last_embedding_model, embedding)+ # Both components are configured independently at start.+ self.assertIs(fake.last_chat_model, chat)++ async def test_no_embedding_model_no_injection(self) -> None:+ """Without an embedding_model, ReMe's embedding stays untouched."""+ fake = _FakeReMeApp()+ mw = _mw(+ app=fake,+ mode="static_control",+ chat_model=RecordingMockModel(context_size=100_000),+ )+ agent = self._agent(mw)+ await agent.reply(UserMsg("user", "hi"))+ self.assertIsNone(mw._parameters.embedding_model)+ self.assertIsNone(fake.last_embedding_model)+++# ----------------------------------------------------------------------+# Agent-control mode+# ----------------------------------------------------------------------+++class TestAgentControlMode(IsolatedAsyncioTestCase):+ """Tools are listed, but no automatic memory hook behavior."""++ async def asyncSetUp(self) -> None:+ """Create a fresh recording model and empty toolkit."""+ self.model = RecordingMockModel(context_size=100_000)+ self.toolkit = Toolkit()++ async def _agent(+ self,+ middleware: ReMeMiddleware,+ *,+ name: str = "a",+ system_prompt: str = "p",+ responses: list[str] | None = None,+ ) -> Agent:+ """Build an agent with tools explicitly listed by middleware."""+ self.model.set_responses(+ [_single_response(r) for r in (responses or ["ok"])],+ )+ self.toolkit = Toolkit(tools=await middleware.list_tools())+ return Agent(+ name=name,+ system_prompt=system_prompt,+ model=self.model,+ toolkit=self.toolkit,+ middlewares=[middleware],+ )++ async def test_tools_listed_and_hint_in_prompt(self) -> None:+ """Agent-control mode should expose the search tool + prompt nudge."""+ fake = _FakeReMeApp(search_return=["found"])+ mw = _mw(+ app=fake,+ mode="agent_control",+ )+ agent = await self._agent(mw, system_prompt="base prompt")+ await agent.reply(UserMsg("user", "hello"))++ basic = _find_group(self.toolkit, "basic")+ names = [t.name for t in basic.tools]+ self.assertIn("memory_search", names)+ # ReMe has no manual add tool — writing is automatic.+ self.assertNotIn("add_memory", names)++ # No automatic retrieval ran — agent_control leaves search to the+ # tool...+ self.assertEqual(fake.search_calls, [])+ # ...but write-back is automatic in every mode (ReMe listens to+ # the conversation via the reply hook).+ self.assertEqual(len(fake.auto_memory_calls), 1)++ # System prompt got a short nudge mentioning the tool.+ msgs = self.model.last_call_messages+ prompt_text = msgs[0].get_text_content()+ self.assertIn("base prompt", prompt_text)+ self.assertIn("Long-term memory", prompt_text)+ self.assertIn("memory_search", prompt_text)+ # No synthetic memory message was injected in agent_control mode.+ for m in msgs:+ self.assertNotEqual(getattr(m, "name", None), "memory")++ async def test_middleware_does_not_mutate_toolkit(self) -> None:+ """Middleware should not register tools unless caller does so."""+ fake = _FakeReMeApp()+ mw = _mw(+ app=fake,+ mode="agent_control",+ )+ self.model.set_responses([_single_response("ok")])+ toolkit = Toolkit()+ agent = Agent(+ name="a",+ system_prompt="base prompt",+ model=self.model,+ toolkit=toolkit,+ middlewares=[mw],+ )+ await agent.reply(UserMsg("user", "hello"))++ self.assertNotIn("memory_search", _all_tool_names(toolkit))+ self.assertNotIn("add_memory", _all_tool_names(toolkit))++ async def test_memory_search_tool_invokes_reme(self) -> None:+ """The memory_search tool should query ReMe and return results."""+ fake = _FakeReMeApp(search_return=["first fact", "second fact"])+ mw = _mw(+ app=fake,+ mode="agent_control",+ )+ agent = await self._agent(mw, system_prompt="base prompt")+ await agent.reply(UserMsg("user", "hi"))++ search_tool = _find_tool(self.toolkit, "memory_search")+ result = await search_tool(+ query="what does alice like?",+ limit=3,+ )+ result_text = _chunk_text(result)+ self.assertIn("first fact", result_text)+ self.assertIn("second fact", result_text)++ # One ReMe search, using the supplied limit.+ self.assertEqual(len(fake.search_calls), 1)+ self.assertEqual(+ fake.search_calls[0]["query"],+ "what does alice like?",+ )+ self.assertEqual(fake.search_calls[0]["limit"], 3)++ async def test_memory_search_default_limit_is_top_k(self) -> None:+ """Omitting ``limit`` should fall back to the middleware's top_k.++ The tool advertises ``top_k`` as the schema default and resolves an+ omitted ``limit`` through it, so configuring ``top_k`` governs the+ agent-facing tool, not just static-control retrieval.+ """+ fake = _FakeReMeApp(search_return=["fact"])+ mw = _mw(+ app=fake,+ mode="agent_control",+ top_k=11,+ )+ agent = await self._agent(mw)+ await agent.reply(UserMsg("user", "hi"))++ search_tool = _find_tool(self.toolkit, "memory_search")+ # Schema advertises top_k as the default.+ self.assertEqual(+ search_tool.input_schema["properties"]["limit"]["default"],+ 11,+ )++ # Calling without a limit uses top_k.+ await search_tool(query="what does alice like?")+ self.assertEqual(fake.search_calls[-1]["limit"], 11)++ async def test_memory_search_no_results(self) -> None:+ """An empty workspace yields a friendly no-results message."""+ fake = _FakeReMeApp(search_return=[])+ mw = _mw(+ app=fake,+ mode="agent_control",+ )+ agent = await self._agent(mw)+ await agent.reply(UserMsg("user", "hi"))+ search_tool = _find_tool(self.toolkit, "memory_search")++ result = await search_tool(query="anything", limit=5)+ self.assertIn("no relevant memories", _chunk_text(result).lower())++ async def test_memory_search_failure_returns_error_chunk(self) -> None:+ """ReMe raising during search yields a ToolChunk state=ERROR."""+ from agentscope.message import ToolResultState++ fake = _FakeReMeApp()+ fake.search_error = RuntimeError("reme down")+ mw = _mw(+ app=fake,+ mode="agent_control",+ )+ agent = await self._agent(mw)+ await agent.reply(UserMsg("user", "hi"))+ search_tool = _find_tool(self.toolkit, "memory_search")++ result = await search_tool(query="q", limit=5)+ self.assertIsInstance(result, ToolChunk)+ self.assertEqual(result.state, ToolResultState.ERROR)+ self.assertIn("reme down", result.content[0].text)++ async def test_tools_auto_allow_permission(self) -> None:+ """The memory tool should be auto-allowed by permission checks."""+ mw = _mw(+ app=_FakeReMeApp(),+ mode="agent_control",+ )+ agent = await self._agent(mw)+ await agent.reply(UserMsg("user", "hi"))++ search_tool = _find_tool(self.toolkit, "memory_search")+ decision_search = await search_tool.check_permissions({}, None)+ self.assertEqual(decision_search.behavior, PermissionBehavior.ALLOW)++ async def test_no_add_memory_tool_exposed(self) -> None:+ """ReMe exposes search only — there is no manual add tool."""+ mw = _mw(+ app=_FakeReMeApp(),+ mode="agent_control",+ )+ tools = await mw.list_tools()+ names = [t.name for t in tools]+ self.assertEqual(names, ["memory_search"])++ async def test_agent_control_writes_back_automatically(self) -> None:+ """Even with no add tool, agent_control writes via the reply hook."""+ fake = _FakeReMeApp()+ mw = _mw(+ app=fake,+ mode="agent_control",+ )+ agent = await self._agent(mw, responses=["sure thing"])+ # session_id is sourced from the agent, not the middleware.+ agent.state.session_id = "alice-001"+ await agent.reply(UserMsg("user", "remember I like tea"))++ # No auto-retrieval in agent_control...+ self.assertEqual(fake.search_calls, [])+ # ...but the exchange was written back automatically.+ self.assertEqual(len(fake.auto_memory_calls), 1)+ write = fake.auto_memory_calls[0]+ self.assertEqual(write["session_id"], "alice-001")+ written_texts = [_msg_text(m) for m in write["messages"]]+ self.assertIn("remember I like tea", written_texts)+ self.assertIn("sure thing", written_texts)+++# ----------------------------------------------------------------------+# Both mode — hooks + tools together+# ----------------------------------------------------------------------+++class TestBothMode(IsolatedAsyncioTestCase):+ """Tests for combined static-control and agent-control behavior."""++ async def test_memory_msg_and_tool_hint_both_present(self) -> None:+ """Both mode should inject memory and expose memory tools."""+ model = RecordingMockModel(context_size=100_000)+ fake = _FakeReMeApp(search_return=["auto-injected"])+ mw = _mw(+ app=fake,+ mode="both",+ )+ # Echo tool forces a second reasoning step so the background+ # auto-retrieval injects before the final model call.+ toolkit = Toolkit(tools=[*await mw.list_tools(), _EchoTool()])+ model.set_responses(_echo_then_text("ok"))+ agent = Agent(+ name="a",+ system_prompt="base",+ model=model,+ toolkit=toolkit,+ middlewares=[mw],+ )+ await agent.reply(UserMsg("user", "hi"))++ # Static hooks ran — one background search (the echo tool call does+ # not search), one write-back.+ self.assertEqual(len(fake.search_calls), 1)+ self.assertEqual(len(fake.auto_memory_calls), 1)++ msgs = model.last_call_messages++ # System prompt has the tool nudge (from on_system_prompt).+ prompt_text = msgs[0].get_text_content()+ self.assertIn("Long-term memory", prompt_text)+ self.assertIn("memory_search", prompt_text)++ # Memory injected as a synthetic HintBlock Msg.+ memory_msgs = [m for m in msgs if getattr(m, "name", None) == "memory"]+ self.assertEqual(len(memory_msgs), 1)+ memory_hints = memory_msgs[0].get_content_blocks("hint")+ self.assertEqual(len(memory_hints), 1)+ self.assertIn("auto-injected", memory_hints[0].hint)++ # Search tool exposed (and no add tool — writing is automatic).+ names = _all_tool_names(toolkit)+ self.assertIn("memory_search", names)+ self.assertNotIn("add_memory", names)