Long-Term Memory - AgentScope

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.
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?")

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.

​Agentic Memory

​Mem0

​Installation

​Quick start

​Control modes

​Construction paths

​Key parameters

​Agent-callable tools

Agentic Memory

Mem0

Installation

Quick start

Control modes

Construction paths

Key parameters

Agent-callable tools