Long-Term Memory

Long-term memory is an agent’s ability to retain information across sessions, including user preferences, past decisions, and knowledge or rules summarized from conversations. AgentScope implements different long-term memory capabilities as agent middleware. Each long-term memory implementation is a MiddlewareBase subclass that non-invasively handles memory injection, retrieval, and write-back. AgentScope currently supports the following long-term memory implementations, with more under development:

Name	Code API	Description
Agentic Memory	`AgenticMemoryMiddleware`	Markdown-file-based long-term memory that agents create, maintain, and use autonomously.
ReMe	`ReMeMiddleware`	An in-process, file-based long-term memory powered by ReMe, which automatically extracts and writes back memories from conversations.
Mem0	`Mem0Middleware`	A drop-in long-term memory backend powered by mem0.
More coming …

Agentic Memory

Agentic Memory is AgentScope’s native long-term memory implementation. It provides long-term memory through Markdown file reads, writes, and retrieval. At runtime, the agent autonomously creates Markdown memory files, maintains an index of all memory files in a fixed MEMORY.md file, and automatically injects that index into the system prompt. This follows a “progressive disclosure” pattern.

Agentic Memory supports different runtime environments through the backend parameter, such as local, Docker, E2B, and cloud sandboxes. It uses LocalBackend by default.

At runtime, the agent uses the built-in Read, Write, and Edit tools to create, access, and modify long-term memory. A typical file structure looks like this:

<workdir>/Memory/
├── MEMORY.md
├── <agent_created_topic>.md
├── <agent_created_feedback>.md
└── ...

Each Markdown file follows the frontmatter convention and includes name, description, and type fields for later retrieval and injection:

---
name: {{memory name}}
description: {{one-line description — used to decide relevance in future conversations, so be specific}}
type: {{user, feedback, project, reference}}
---

{{memory content — for feedback/project types, structure as: rule/fact, then **Why:** and **How to apply:** lines}}

MEMORY.md stays short. It serves only as an index and is automatically injected into the system prompt. For example:

- [User profile](user_profile.md) — User location and answer-style preference.
- [Feedback on answer style](feedback_answer_style.md) — User prefers concise Chinese answers.

Agentic Memory has two retrieval paths. First, the agent can autonomously retrieve relevant files based on the prompt and the MEMORY.md index. Second, when reply / reply_stream is called, the middleware starts an async task that asks an LLM to select relevant Markdown files, then checks before later reasoning steps whether that task has finished and injects the retrieved results as a HintBlock. Note that retrieval is asynchronous: injection happens at checkpoints before reasoning starts inside the reasoning-acting loop, and the exact timing depends on retrieval latency. If the current reply does not enter a later reasoning round, such as when the model produces no tool calls, the retrieved long-term memory may not be injected into that reply. The workflow is: Use Agentic Memory in different environments as follows:

from agentscope.agent import Agent
from agentscope.middleware import AgenticMemoryMiddleware
from agentscope.permission import AdditionalWorkingDirectory, PermissionMode
from agentscope.tool import Read, Toolkit, Write, Edit


workdir = "/tmp/agentscope_ltm_demo"
memory = AgenticMemoryMiddleware(workdir=workdir)

agent = Agent(
    name="assistant",
    system_prompt="You are a helpful assistant.",
    model=my_chat_model,
    toolkit=Toolkit(tools=[Read(), Write(), Edit()]),
    middlewares=[memory],
)

# Optional: allow the Write tool in this example to write into workdir.
# In production, configure permissions according to your security policy.
agent.state.permission_context.mode = PermissionMode.ACCEPT_EDITS
agent.state.permission_context.working_directories[workdir] = (
    AdditionalWorkingDirectory(path=workdir, source="long-term-memory-demo")
)

await agent.reply("Remember that I live in Hangzhou and prefer concise Chinese answers.")

# Recreate an agent. Reusing the same workdir reuses the same Markdown memories.
new_agent = Agent(
    name="assistant",
    system_prompt="You are a helpful assistant.",
    model=my_chat_model,
    toolkit=Toolkit(tools=[Read(), Write(), Edit()]),
    middlewares=[AgenticMemoryMiddleware(workdir=workdir)],
)

await new_agent.reply("Do you remember my location and answer style preference?")

from agentscope.agent import Agent
from agentscope.middleware import AgenticMemoryMiddleware
from agentscope.tool import Read, Toolkit, Write
from agentscope.workspace import DockerWorkspace


workspace = DockerWorkspace()
await workspace.initialize()

# Get the Docker sandbox backend.
backend = workspace.get_backend()
memory = AgenticMemoryMiddleware(
    workdir=workspace.workdir,
    # Switch to the sandbox environment.
    backend=backend,
)

agent = Agent(
    name="assistant",
    system_prompt="You are a helpful assistant.",
    model=my_chat_model,
    toolkit=Toolkit(
        # Docker workspace tools include Read / Write / Edit by default.
        tools=await workspace.list_tools(),
        # You can also pass Read / Write / Edit yourself.
        # tools=[Read(backend=backend), Write(backend=backend), Edit(backend=backend)],
    ),
    middlewares=[memory],
)

try:
    await agent.reply("Remember that I am testing long-term memory in a Docker sandbox.")
finally:
    await workspace.close()

from agentscope.agent import Agent
from agentscope.middleware import AgenticMemoryMiddleware
from agentscope.tool import Read, Toolkit, Write
from agentscope.workspace import E2BWorkspace


workspace = E2BWorkspace()
await workspace.initialize()

# Get the E2B sandbox backend.
backend = workspace.get_backend()
memory = AgenticMemoryMiddleware(
    workdir=workspace.workdir,
    # Switch to the sandbox environment.
    backend=backend,
)

agent = Agent(
    name="assistant",
    system_prompt="You are a helpful assistant.",
    model=my_chat_model,
    toolkit=Toolkit(
        # E2B workspace tools include Read / Write / Edit by default.
        tools=await workspace.list_tools(),
        # You can also pass Read / Write / Edit yourself.
        # tools=[Read(backend=backend), Write(backend=backend), Edit(backend=backend)],
    ),
    middlewares=[memory],
)

try:
    await agent.reply("Remember that I am testing long-term memory in an E2B sandbox.")
finally:
    await workspace.close()

ReMe

ReMe is a file-based memory toolkit maintained by the AgentScope team. ReMeMiddleware embeds ReMe in the current process, so no separate service is required. It listens to the agent’s conversations and automatically extracts and writes back memories through ReMe’s auto_memory job after each reply. The agent does not save memories itself, and ReMe does not provide a manual memory-add tool.

The ReMe workspace is specified by workspace_dir and stores memory cards and search indexes. Reusing the same workspace across sessions enables cross-session recall.

Installation

ReMeMiddleware’s dependencies are available as an optional AgentScope extra:

pip install "agentscope[reme]"

Quick start

You can inject AgentScope chat and embedding models into ReMe. The chat model drives auto_memory extraction; providing an embedding model automatically enables vector search with the default configuration. Replace my_chat_model and my_embedding_model below with your model instances:

import asyncio

from agentscope.agent import Agent
from agentscope.middleware import ReMeMiddleware
from agentscope.state import AgentState
from agentscope.tool import Toolkit


async def main():
    memory = ReMeMiddleware(
        workspace_dir=".reme",
        parameters=ReMeMiddleware.Parameters(
            chat_model=my_chat_model,
            embedding_model=my_embedding_model,
            mode="both",
            top_k=5,
        ),
    )

    agent = Agent(
        name="assistant",
        system_prompt="You are a helpful assistant.",
        model=my_chat_model,
        # In both / agent_control modes, add memory_search to the toolkit.
        toolkit=Toolkit(tools=await memory.list_tools()),
        middlewares=[memory],
        # Set a stable ID for a resumable session; AgentState generates one
        # automatically when no ID is provided.
        state=AgentState(session_id="alice-main"),
    )

    try:
        await agent.reply("Remember that I live in Hangzhou and prefer concise Chinese answers.")
    finally:
        # AgentScope does not manage middleware lifecycles automatically.
        await memory.close()


asyncio.run(main())

Without injected models, ReMe creates its LLM and embedding backends from its own configuration and credentials. The default default configuration uses BM25 keyword search for its file store. For semantic search, pass an embedding_model. Its vector dimensions must match the vector store configured for ReMe; the example uses a 1024-dimensional DashScope embedding model.

Control modes

ReMeMiddleware.Parameters.mode defaults to "both" and controls retrieval only; conversation write-back runs automatically in all three modes.

Mode	Behavior
`static_control`	The middleware starts a background search when `reply` begins and injects the results as an `AssistantMsg(name="memory")` hint before a later reasoning step; the agent is unaware of the retrieval. Because search runs concurrently with the reply, a single-model-call reply may finish before the hint can be injected.
`agent_control`	No automatic retrieval. The middleware exposes a `memory_search(query, limit)` tool through `list_tools()` and appends a short usage nudge to the system prompt; the agent decides when to search. The conversation is still written back automatically after the reply.
`both`	Enables both automatic retrieval and the `memory_search` tool.

In static_control mode, await memory.list_tools() returns an empty list. In agent_control and both modes, pass the returned tools into Toolkit as shown above. memory_search is query-only; there is no add_memory tool because writes are always handled automatically by the middleware.

Session scope and lifecycle

Write-back is scoped by agent.state.session_id. Set a stable ID with AgentState(session_id="...") for a resumable session; the ID does not belong on the middleware configuration.
Search spans the entire workspace_dir, rather than only the current session_id. A new agent using the same workspace can therefore recall memories written by an earlier session.
One ReMeMiddleware can safely be shared across multiple agents and sessions. The middleware reads each agent’s session_id at hook time. Call await memory.close() explicitly when the application shuts down.

After auto_memory writes a card, ReMe still needs to index it before it becomes searchable. A search issued immediately after write-back may temporarily miss the new card. The examples/long_term_memory/reme example explicitly triggers indexing after write-back so its demonstration is deterministic.

Key parameters

Location	Parameter	Default	Description
`ReMeMiddleware(...)`	`workspace_dir`	`".reme"`	Directory for ReMe memory cards and indexes.
`ReMeMiddleware(...)`	`config`	`"default"`	ReMe configuration name or configuration file path.
`Parameters`	`chat_model`	`None`	LLM injected into ReMe for `auto_memory`; when omitted, ReMe uses its own configured credentials.
`Parameters`	`embedding_model`	`None`	Embedding model injected into ReMe and enables the vector store; when omitted, ReMe uses its own embedding backend and the default configuration remains BM25-based.
`Parameters`	`mode`	`"both"`	`static_control`, `agent_control`, or `both`.
`Parameters`	`top_k`	`5`	Maximum memories returned by each automatic search and the default `limit` for `memory_search`.

Mem0

Mem0Middleware is a drop-in long-term memory backend powered by mem0. It works with both mem0.AsyncMemory (open-source) and mem0.AsyncMemoryClient (hosted Platform). With mem0.AsyncMemory (open-source), it can route mem0’s own memory extraction and embedding through your existing AgentScope models — so mem0 needs no separate provider key.

Installation

Mem0Middleware’s dependencies are available as an optional extra in AgentScope:

pip install "agentscope[mem0]"

Quick start

The fastest path is to pass your AgentScope chat and embedding models; the middleware builds an open-source mem0 store internally and wires both extraction and embedding through them.

import asyncio

from agentscope.agent import Agent
from agentscope.middleware import Mem0Middleware
from agentscope.tool import Toolkit


async def main():
    mw = Mem0Middleware(
        user_id="alice",
        chat_model=my_chat_model,
        embedding_model=my_embedding_model,
        mode="both",
    )

    agent = Agent(
        name="assistant",
        system_prompt="You are a helpful assistant.",
        model=my_chat_model,
        toolkit=Toolkit(tools=await mw.list_tools()),
        middlewares=[mw],
    )

    # Memories written in this session resurface in later sessions
    # for the same ``user_id``.
    await agent(...)


asyncio.run(main())

Mem0Middleware contributes its search_memory / add_memory tools through list_tools(), which the agent does not call automatically. To make the tools available to the agent, collect them yourself and pass them into the toolkit — Toolkit(tools=await mw.list_tools()). In static_control mode list_tools() returns an empty list.

Control modes

The mode parameter decides how the agent interacts with mem0. It defaults to "both", matching AgentScope 1.x’s ReActAgent.long_term_memory_mode.

Mode	Behavior
`static_control`	The middleware searches mem0 before each reply, injects the retrieved memories into the context as an `AssistantMsg(name="memory")`, and writes the new exchange back after the reply. The agent is unaware of mem0.
`agent_control`	The middleware exposes `search_memory` / `add_memory` tools and appends a short usage nudge to the system prompt. The agent decides when to read from or write to memory; there is no automatic retrieval or write-back.
`both`	Both patterns are active at once — automatic retrieval and on-demand tools.

Construction paths

Mem0Middleware supports three ways to wire up the mem0 backend:

AgentScope models
Models + custom config
Pre-built client

Pass AgentScope models and let the middleware build an open-source AsyncMemory internally (mem0’s default Qdrant store). The embedding model’s dimensions must match the vector store (the default Qdrant expects 1536).

Mem0Middleware(
    user_id="alice",
    chat_model=my_chat_model,
    embedding_model=my_embedding_model,
)

Start from your own mem0.configs.base.MemoryConfig to customize the vector store, history DB, or reranker, while still routing the LLM and embedder through AgentScope. Only the .llm / .embedder slots are overridden; every other field is preserved.

Mem0Middleware(
    user_id="alice",
    chat_model=my_chat_model,
    embedding_model=my_embedding_model,
    mem0_config=my_mem0_config,
)

Pass a pre-built mem0 client when you want full control (e.g. the hosted Platform, or sharing one store across agents). When client is given it takes absolute precedence, and chat_model / embedding_model / mem0_config are ignored.

from mem0 import AsyncMemoryClient

Mem0Middleware(
    user_id="alice",
    client=AsyncMemoryClient(api_key="m0-..."),
)

Mem0Middleware requires an async mem0 client (mem0.AsyncMemory or mem0.AsyncMemoryClient). The synchronous Memory / MemoryClient are not supported.

Key parameters

Parameter	Type	Default	Description
`user_id`	`str`	(required)	mem0 namespace for the user’s memories.
`mode`	`"static_control" \| "agent_control" \| "both"`	`"both"`	How the agent interacts with mem0 (see above).
`agent_id`	`str \| None`	`None`	Optional finer-grained namespace.
`top_k`	`int`	`5`	Max memories retrieved per static-control search; also the default for the `search_memory` tool.
`threshold`	`float \| None`	`None`	Minimum similarity score; `None` lets mem0 decide.
`scope_search_by_agent`	`bool`	`True`	When `True`, searches filter by both `user_id` and `agent_id`; when `False`, a user’s memories are shared across agents.
`await_write`	`bool`	`True`	When `True`, the post-turn write is awaited inline; when `False`, it’s fire-and-forget (faster, but exceptions only surface in logs).

Agent-callable tools

In agent_control and both modes, the middleware contributes two tools the model can invoke on demand:

search_memory(keywords, limit=5) — retrieves memories using a list of short, targeted keywords. Each keyword is issued as an independent query; results are merged and deduplicated.
add_memory(thinking, content) — records durable facts. Only content (a list of standalone sentences) is persisted to mem0; thinking stays in the transcript for auditability.

Both tools auto-allow themselves and read user_id / agent_id directly from the middleware instance, so they require no extra wiring beyond adding them to the toolkit.

Get Started

Building Blocks

Agent as Service

Others

Agentic Memory

ReMe

Installation

Quick start

Control modes

Session scope and lifecycle

Key parameters

Mem0

Installation

Quick start

Control modes

Construction paths

Key parameters

Agent-callable tools

​Agentic Memory

​ReMe

​Installation

​Quick start

​Control modes

​Session scope and lifecycle

​Key parameters

​Mem0

​Installation

​Quick start

​Control modes

​Construction paths

​Key parameters

​Agent-callable tools

Agentic Memory

ReMe

Installation

Quick start

Control modes

Session scope and lifecycle

Key parameters

Mem0

Installation

Quick start

Control modes

Construction paths

Key parameters

Agent-callable tools