DeepAgents : 记忆机制（Memory）

在 DeepAgents 中，记忆即文件。智能体通过读写特定路径下的文件（如 /memories/）来维持长期记忆。这套机制的核心设计围绕 “作用域（Scoping）” 与 “权限（Permissions）” 展开。

1. 核心：用“命名空间”实现记忆隔离

记忆的隔离级别由后端的 namespace 决定。你需要根据业务场景选择合适的颗粒度：

配置模板（用户级 + 智能体级混合）

from deepagents import create_deep_agent
from deepagents.backends import CompositeBackend, StateBackend, StoreBackend

agent = create_deep_agent(
    model="...",
    # 声明路径，告诉智能体这些位置存有记忆
    memory=["/memories/preferences.md"],
    skills=["/skills/"],  # 技能本质上也是一种程序性记忆
    backend=CompositeBackend(
        default=StateBackend(),  # 临时会话文件
        routes={
            # 用户偏好：按用户隔离（可读写）
            "/memories/": StoreBackend(
                namespace=lambda rt: (rt.server_info.user.identity,)
            ),
            # 组织策略：按组织隔离（建议只读，见下文安全提示）
            "/policies/": StoreBackend(
                namespace=lambda rt: (rt.context.org_id,)
            ),
        },
    ),
)

2. 关键决策：谁来写入，何时写入？

1. 热路径写入（默认）

智能体在对话过程中直接调用 edit_file 修改记忆文件。优点是即时生效（下一次对话立刻感知）；缺点是增加当前轮次的延迟。

• 适用：用户主动要求的偏好变更（如“记住我喜欢 Python”）。

2. 后台整合（推荐用于复杂推理）

部署一个独立的“整合智能体”（Consolidation Agent），通过 Cron 定时任务在后台提炼多轮对话的精华，合并到主记忆文件中。

• 优点：不干扰主智能体响应速度，且能提炼跨会话的抽象知识。
• 注意：Cron 回溯窗口必须与运行频率匹配（如每 6 小时运行一次，则只回溯最近 6 小时的对话）。

整合智能体核心逻辑

@tool
async def search_recent_conversations(runtime: ToolRuntime):
    # 拉取最近 6 小时该用户的对话线程
    user_id = runtime.server_info.user.identity
    threads = await client.threads.search(metadata={"user_id": user_id}, updated_after=...)
    # 返回历史消息供 LLM 总结提炼

3. 安全红线：只读策略防止提示注入

如果记忆文件（尤其是组织级策略）允许智能体写入，恶意用户可能通过对话向全局记忆注入有害指令。

最佳实践配置：

• 用户偏好：可读写（默认，仅用户自己受影响）。
• 组织策略 / 核心技能：只读（通过应用代码或 Store API 预置内容，拒绝智能体修改）。

实施方式：在 CompositeBackend 的对应路由中配置权限钩子（Policy Hooks），拦截针对敏感路径（如 /policies/）的 edit_file 请求。

4. 补充：情景记忆（对话历史检索）

除了静态文件，过往的完整对话线程（Threads）也是一种记忆。你可以将搜索历史线程封装成工具，让智能体在需要时回顾旧案例：

@tool
async def search_past_threads(query: str, runtime: ToolRuntime):
    # 根据 user_id 搜索历史检查点（Checkpoints）
    threads = await client.threads.search(metadata={"user_id": user_id}, limit=5)
    # 返回历史消息记录

5. 避坑指南

1. 并发写入冲突：多个线程同时写同一个用户文件（尤其是智能体级记忆）会发生覆盖。建议策略——将知识分散到不同主题的文件中，或依赖后台整合的单线程序列化写入来规避。
2. 命名空间取值：rt.server_info.assistant_id 和 user.identity 需要 deepagents>=0.5.0。旧版本请从 get_config()["metadata"] 中读取。
3. 上下文膨胀：不要一股脑把所有记忆文件塞进 System Prompt。善用 Skills 机制（按需加载）：启动时只读文件名/描述，匹配到具体任务才加载完整文件内容。