Appearance
长期记忆
Deep Agents 把 memory 表达为虚拟文件。memory 参数声明哪些文件始终加入启动上下文，backend 决定这些路径存在哪里、对谁可见以及能否跨 thread 持久化。
先区分三种生命周期
| 内容 | 保存位置 | 生命周期 | 示例 |
|---|---|---|---|
| 当前工作状态 | Agent state/checkpoint | 当前 thread | messages、todos、草稿文件 |
| Agent-scoped memory | StoreBackend namespace | 同一个 assistant 的多个 thread | 项目约定、Agent 经验 |
| User-scoped memory | StoreBackend namespace | 同一个用户的多个 thread | 偏好、已确认背景 |
前端类比
当前 thread state 类似页面组件 state；Agent-scoped memory 类似应用级配置；User-scoped memory 类似按账户隔离的服务端 profile。它们不能只靠文件名区分，必须由存储 namespace 强制隔离。
Deep Agents 原生语义：memory=[...] 让 MemoryMiddleware 读取指定虚拟文件并加入 system prompt。是否跨 thread 取决于这些路径是否路由到 StoreBackend，以及 namespace 是否从可信 runtime context 派生。
配置 Memory 文件
python
import os
from deepagents import create_deep_agent
agent = create_deep_agent(
model=os.environ["DEEPAGENTS_MODEL"],
memory=["/memories/AGENTS.md"],
)ts
import { createDeepAgent } from 'deepagents'
const model = process.env.DEEPAGENTS_MODEL
if (!model) throw new Error('DEEPAGENTS_MODEL is required')
const agent = createDeepAgent({
model,
memory: ['/memories/AGENTS.md'],
})如果仍使用默认 StateBackend，这个文件只属于当前 thread 的 state。要获得跨 thread memory，需要把 /memories/ 路由到持久 StoreBackend。
使用 StoreBackend 隔离 namespace
下面展示 Python 的核心形状。示例使用 user_id 说明语义；生产代码必须从已认证 context 获取它， 不能接受模型或未经验证的请求参数直接指定 namespace。
python
import os
from dataclasses import dataclass
from deepagents import create_deep_agent
from deepagents.backends import CompositeBackend, StateBackend, StoreBackend
@dataclass
class Context:
user_id: str
backend = CompositeBackend(
default=StateBackend(),
routes={
"/memories/": StoreBackend(
namespace=lambda runtime: ("users", runtime.context.user_id),
)
},
)
agent = create_deep_agent(
model=os.environ["DEEPAGENTS_MODEL"],
memory=["/memories/AGENTS.md"],
backend=backend,
context_schema=Context,
)Store 的实际实现需要在 Agent Runtime 或部署环境中提供。示例只展示路由与 namespace，不代表 StateBackend 会自动升级成持久数据库。
什么值得记住
适合长期 memory：
- 用户明确确认且未来仍有用的偏好。
- 稳定的项目规范与术语。
- 已验证的工具使用经验或失败模式。
- 可以追溯来源和更新时间的事实。
不适合：一次性工具输出、未经确认的模型推断、短期任务 Todo、密钥和访问令牌、受法规限制但 没有删除机制的数据。
写入与遗忘策略
Memory 不应只增不减。应用需要定义：
- 谁可以创建、修改和删除 memory。
- 哪些事实需要用户确认。
- 冲突时按时间、来源还是权限级别解决。
- 每条信息的来源、更新时间和过期时间。
- 用户如何查看、导出与删除数据。
- trace 和备份如何同步执行删除政策。
Memory 与 Skills
- Memory 回答“这个 Agent 或用户已经知道什么”。
- Skills 回答“遇到某类任务时应该怎么做”。
Memory 通常始终进入启动上下文，应保持短小；Skills 通过 metadata 发现、正文按需加载，更适合 较长流程说明。
Python 与 TypeScript
两个 SDK 都使用 memory 文件路径和 backend 路由。字段命名、runtime context 与 Store 构造器 存在语言差异；TypeScript 应使用当前 CreateDeepAgentParams 与 backend 文档，不要直接复制 Python 的 dataclass 或 snake_case 字段。