Skip to content

Build and run agents you can see, understand and trust.

feat(middleware): add ReMe long-term memory middleware (#1972)

Sen Huang922e673b0e3d
diff --git a/README.md b/README.md
index 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.md
index 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.md
index 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.md
index 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.md
new file mode 100644
index 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.py
new file mode 100644
index 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.toml
index 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__.py
index 38f888648..822b56c43 100644
--- a/src/agentscope/middleware/__init__.py
+++ b/src/agentscope/middleware/__init__.py
@@ -4,7 +4,11 @@
from ._base import MiddlewareBase
from ._rag import RAGMiddleware
from ._budget import ReplyBudgetControlMiddleware
-from ._longterm_memory import AgenticMemoryMiddleware, Mem0Middleware
+from ._longterm_memory import (
+ AgenticMemoryMiddleware,
+ Mem0Middleware,
+ ReMeMiddleware,
+)
from ._tracing import TracingMiddleware
from ._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__.py
index 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 AgenticMemoryMiddleware
from ._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__.py
new file mode 100644
index 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.py
new file mode 100644
index 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.py
new file mode 100644
index 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.py
new file mode 100644
index 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 out
diff --git a/tests/reme_middleware_test.py b/tests/reme_middleware_test.py
new file mode 100644
index 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)