在 AgentScope 中，要让对话时自动调用长期记忆，取决于你选择的 long_term_memory_mode。两种模式都能实现“自动”，但机制不同：

• static_control：框架在每次回复开始时自动检索、结束时自动记录，无需智能体主动调用工具。
• agent_control：框架将 retrieve_from_memory 与 record_to_memory 注册为工具，智能体通过工具调用自主决定何时检索/记录；通常需要在系统提示中引导其调用。

下面分别说明两种模式的实现方式与调用时机。

---

1. static_control：框架自动检索与记录

机制

• 在 ReActAgent.reply 开始时调用 _retrieve_from_long_term_memory(msg)，若存在长期记忆且 _static_control 为真，则检索并将结果以 <long_term_memory> 标签插入短期记忆 1 。
• 在 reply 结束时，若 _static_control 为真，调用 long_term_memory.record 将本轮对话（排除已压缩消息）存入长期记忆 2 。

配置示例

agent = ReActAgent(
    name="Friday",
    sys_prompt="你是一个具有长期记忆功能的助手。",
    model=DashScopeChatModel(...),
    formatter=DashScopeChatFormatter(),
    memory=InMemoryMemory(),
    long_term_memory=Mem0LongTermMemory(...),
    long_term_memory_mode="static_control",  # 关键参数
)

• 完整示例见 docs/tutorial/zh_CN/src/task_long_term_memory.py（创建与测试） 3 ；清空短期记忆后提问仍能回答，证明自动检索生效 4 。

---

2. agent_control：智能体通过工具自主管理

机制

• 构造时若 _agent_control 为真，自动注册 retrieve_from_memory 与 record_to_memory 到工具包 5 。
• 智能体在推理过程中可调用这些工具（例如在用户提问偏好前先检索，在用户分享信息后记录）。
• 为提高调用率，建议在系统提示中明确何时调用工具（见下文示例）。

配置与提示示例

agent = ReActAgent(
    name="Friday",
    sys_prompt=(
        "你是一个名为 Friday 的助手，具有长期记忆能力。\n\n"
        "## 记忆管理指南：\n"
        "1. **记录记忆**：当用户分享个人信息、偏好、习惯或事实时，"
        "始终使用 `record_to_memory` 记录。\n"
        "2. **检索记忆**：在回答关于用户偏好或过去信息的问题前，"
        "必须先调用 `retrieve_from_memory`。\n"
        "3. **何时检索**：用户问'我喜欢什么？'、'我的偏好？'、'你对我了解多少？'等时先检索。\n"
    ),
    model=DashScopeChatModel(...),
    formatter=DashScopeChatFormatter(),
    memory=InMemoryMemory(),
    long_term_memory=Mem0LongTermMemory(...),
    long_term_memory_mode="agent_control",  # 关键参数
)

• 完整示例见 docs/tutorial/zh_CN/src/task_long_term_memory.py（创建与测试） 6 ；清空短期记忆后提问仍能回答，证明智能体主动调用了检索工具 7 。

---

3. 两种模式对比

模式	自动性	适用场景	配置方式
static_control	框架在每次回复前后自动检索/记录	希望每次对话都自动注入历史上下文，无需智能体判断	long_term_memory_mode="static_control"
agent_control	智能体通过工具自主决定何时检索/记录	需要更精细控制（例如仅在特定话题检索）或结合多步推理	long_term_memory_mode="agent_control" + 系统提示引导

• 也可设为 "both" 同时启用两种机制 8 。

---

4. 长期记忆实现类

• AgentScope 提供 Mem0LongTermMemory（基于 mem0）和 ReMePersonalLongTermMemory 等实现，均需实现 record/retrieve（static 用）与 record_to_memory/retrieve_from_memory（agent 用） 9 。
• 创建时需传入模型与嵌入模型等，例如 Mem0LongTermMemory 的构造 10 。

---

5. 完整流程（static_control）

---

Notes

• 若使用 agent_control，务必在系统提示中明确指导何时调用工具，否则智能体可能不主动检索或记录。
• static_control 会为每轮对话都检索一次，适合需要持续上下文的场景；agent_control 更灵活但依赖模型遵循指令。
• 示例代码中清空短期记忆（memory.clear()）是为了验证长期记忆是否生效，实际使用时无需清空。
• 长期记忆的持久化由具体实现类决定（如 Mem0LongTermMemory 的 on_disk 参数） 10 。

Wiki pages you might want to explore:

• Quick Start: Building Your First Agent (agentscope-ai/agentscope)

Citations

File: src/agentscope/agent/_react_agent.py (L185-190)

        long_term_memory: LongTermMemoryBase | None = None,
        long_term_memory_mode: Literal[
            "agent_control",
            "static_control",
            "both",
        ] = "both",

File: src/agentscope/agent/_react_agent.py (L301-308)

        if self._agent_control:
            # Adding two tool functions into the toolkit to allow self-control
            self.toolkit.register_tool_function(
                long_term_memory.record_to_memory,
            )
            self.toolkit.register_tool_function(
                long_term_memory.retrieve_from_memory,
            )

File: src/agentscope/agent/_react_agent.py (L398-402)

        # -------------- Retrieval process --------------
        # Retrieve relevant records from the long-term memory if activated
        await self._retrieve_from_long_term_memory(msg)
        # Retrieve relevant documents from the knowledge base(s) if any
        await self._retrieve_from_knowledge(msg)

File: src/agentscope/agent/_react_agent.py (L527-535)

        # Post-process the memory, long-term memory
        if self._static_control:
            await self.long_term_memory.record(
                [
                    *await self.memory.get_memory(
                        exclude_mark=_MemoryMark.COMPRESSED,
                    ),
                ],
            )

File: docs/tutorial/zh_CN/src/task_long_term_memory.py (L37-51)

# 创建 mem0 长期记忆实例
long_term_memory = Mem0LongTermMemory(
    agent_name="Friday",
    user_name="user_123",
    model=DashScopeChatModel(
        model_name="qwen-max-latest",
        api_key=os.environ.get("DASHSCOPE_API_KEY"),
        stream=False,
    ),
    embedding_model=DashScopeTextEmbedding(
        model_name="text-embedding-v2",
        api_key=os.environ.get("DASHSCOPE_API_KEY"),
    ),
    on_disk=False,
)

File: docs/tutorial/zh_CN/src/task_long_term_memory.py (L90-103)

# 创建带有长期记忆的 ReAct 智能体
agent = ReActAgent(
    name="Friday",
    sys_prompt="你是一个具有长期记忆功能的助手。",
    model=DashScopeChatModel(
        api_key=os.environ.get("DASHSCOPE_API_KEY"),
        model_name="qwen-max-latest",
    ),
    formatter=DashScopeChatFormatter(),
    toolkit=Toolkit(),
    memory=InMemoryMemory(),
    long_term_memory=long_term_memory,
    long_term_memory_mode="static_control",  # 使用 static_control 模式
)

File: docs/tutorial/zh_CN/src/task_long_term_memory.py (L120-130)

async def retrieve_preferences():
    """Retrieve user preferences from long-term memory"""
    # 我们清空智能体的短期记忆，以避免造成干扰
    await agent.memory.clear()

    # 测试智能体是否会记住之前的对话
    msg2 = Msg("user", "我有什么偏好？简要的回答我", "user")
    await agent(msg2)


asyncio.run(retrieve_preferences())

File: docs/tutorial/zh_CN/src/task_long_term_memory.py (L287-319)

#     # 创建带有长期记忆的 ReAct 智能体（agent_control 模式）
#     async def test_react_agent_with_reme():
#         """测试 ReActAgent 与 ReMe 个人记忆的集成"""
#         async with reme_long_term_memory:
#             agent_with_reme = ReActAgent(
#                 name="Friday",
#                 sys_prompt=(
#                     "你是一个名为 Friday 的助手，具有长期记忆能力。"
#                     "\n\n## 记忆管理指南：\n"
#                     "1. **记录记忆**：当用户分享个人信息、偏好、习惯或关于自己的事实时，"
#                     "始终使用 `record_to_memory` 记录这些信息以供将来参考。\n"
#                     "\n2. **检索记忆**：在回答关于用户偏好、过去信息或个人详细信息的问题之前，"
#                     "你必须首先调用 `retrieve_from_memory` 来检查是否有任何相关的存储信息。"
#                     "不要仅依赖当前对话上下文。\n"
#                     "\n3. **何时检索**：在以下情况下调用 `retrieve_from_memory`：\n"
#                     "   - 用户问类似'我喜欢什么？'、'我的偏好是什么？'、"
#                     "'你对我了解多少？'的问题\n"
#                     "   - 用户询问他们过去的行为、习惯或偏好\n"
#                     "   - 用户提到他们之前提到的信息\n"
#                     "   - 你需要关于用户的上下文来提供个性化的响应\n"
#                     "\n在声称不了解用户的某些信息之前，始终先检查你的记忆。"
#                 ),
#                 model=DashScopeChatModel(
#                     model_name="qwen3-max",
#                     api_key=os.environ.get("DASHSCOPE_API_KEY"),
#                     stream=False,
#                 ),
#                 formatter=DashScopeChatFormatter(),
#                 toolkit=Toolkit(),
#                 memory=InMemoryMemory(),
#                 long_term_memory=reme_long_term_memory,
#                 long_term_memory_mode="agent_control",  # 使用 agent_control 模式
#             )

File: docs/tutorial/zh_CN/src/task_long_term_memory.py (L330-336)

#             # 清空短期记忆以测试长期记忆
#             await agent_with_reme.memory.clear()
#
#             # 查询偏好
#             msg2 = Msg(role="user", content="我有什么偏好？", name="user")
#             response2 = await agent_with_reme(msg2)
#             print(f"智能体响应: {response2.get_text_content()}")

File: docs/tutorial/zh_CN/src/task_long_term_memory.py (L371-396)

# 自定义长期记忆
# ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
# AgentScope 提供了 ``LongTermMemoryBase`` 基类，它定义了长期记忆的基本接口。
#
# 开发者可以继承 ``LongTermMemoryBase`` 并实现以下的抽象方法来定义自己的长期记忆类：
#
# .. list-table:: AgentScope 中的长期记忆类
#     :header-rows: 1
#
#     * - 类
#       - 抽象方法
#       - 描述
#     * - ``LongTermMemoryBase``
#       - | ``record``
#         | ``retrieve``
#         | ``record_to_memory``
#         | ``retrieve_from_memory``
#       - - 如果想支持 "static_control" 模式，必须实现 ``record`` 和 ``retrieve`` 方法。
#         - 想要支持 "agent_control" 模式，必须实现 ``record_to_memory`` 和 ``retrieve_from_memory`` 方法。
#     * - ``Mem0LongTermMemory``
#       - | ``record``
#         | ``retrieve``
#         | ``record_to_memory``
#         | ``retrieve_from_memory``
#       - 基于 mem0 库的长期记忆实现，支持向量存储和检索。
#     * - ``ReMePersonalLongTermMemory``