Skip to main content
记忆功能让你的智能体能够在多次对话中学习与改进。Deep Agents 将记忆作为一等公民，提供基于文件系统的记忆机制：智能体以文件形式读写记忆，你可以通过后端控制这些文件的存储位置。
本页介绍的是长期记忆：跨对话持久保存的记忆。关于短期记忆（单次会话内的对话历史和临时文件），请参阅上下文工程指南。短期记忆作为智能体状态的一部分自动管理。

​
记忆工作原理

  1. 为智能体指定记忆文件路径：创建智能体时，通过 memory= 参数传递文件路径。后端控制这些文件的存储位置和访问权限。
  2. 智能体在启动时加载记忆：每次对话开始时，智能体将记忆文件内容读入系统提示词。
  3. 智能体在对话过程中更新记忆：当智能体学习到新信息时，会使用内置的 edit_file 工具更新记忆文件。更改会被持久化，并在下次对话中可用。
两种最常见的模式是智能体作用域记忆（所有用户共享）和用户作用域记忆（按用户隔离）。

​
智能体作用域记忆

为智能体提供一个共享的记忆文件，所有用户都可以读取和写入。随着智能体在每次对话中积累知识，它会随时间不断改进。当拥有写入权限时，它还可以学习和更新技能。参见技能作为程序性记忆。 关键在于后端命名空间：将其设置为 (assistant_id,) 意味着该智能体的每次对话都读写同一个记忆文件。 
from deepagents import create_deep_agent
from deepagents.backends import CompositeBackend, StateBackend, StoreBackend
from langgraph.config import get_config

agent = create_deep_agent(
    memory=["/memories/AGENTS.md"],
    backend=CompositeBackend(
        default=StateBackend(),
        routes={
            "/memories/": StoreBackend(
                namespace=lambda ctx: (
                    get_config()["metadata"]["assistant_id"],
                ),
            ),
        },
    ),
)

​
用户作用域记忆

为每个用户提供其专属的记忆文件。智能体可以记住每位用户的偏好、上下文和历史记录，而核心智能体指令保持不变。如果存储在用户作用域的后端中，用户还可以拥有专属的技能。 命名空间使用 (user_id,)，因此每个用户都获得一个隔离的记忆文件副本。用户 A 的偏好永远不会泄露到用户 B 的对话中。 
from deepagents import create_deep_agent
from deepagents.backends import CompositeBackend, StateBackend, StoreBackend

agent = create_deep_agent(
    memory=["/memories/preferences.md"],
    backend=CompositeBackend(
        default=StateBackend(),
        routes={
            "/memories/": StoreBackend(
                namespace=lambda ctx: (ctx.runtime.context.user_id,),
            ),
        },
    ),
)

​
高级用法

以上部分涵盖了基础知识：配置记忆路径、选择作用域，然后让智能体处理其余部分。本节介绍更高级的模式。
维度它回答的问题选项
持续时间记忆持续多久？短期（单次对话）或长期（跨对话）
信息类型存储什么类型的信息？情景记忆（过往经历）、程序性记忆（指令和技能）或语义记忆（事实）
作用域谁可以查看和修改？用户、智能体或组织
更新策略记忆何时写入？对话期间（默认）或对话之间
检索方式记忆如何读取？加载到提示词中（默认）或按需检索（例如，技能）
智能体权限智能体可以写入记忆吗？读写（默认）或只读（用于共享策略）

​
情景记忆

情景记忆存储过去经历的记录：发生了什么、顺序如何以及结果是什么。与语义记忆（存储在 AGENTS.md 等文件中的事实和偏好）不同，情景记忆保留了完整的对话上下文，使智能体能够回忆如何解决问题，而不仅仅是从中学到了什么。 Deep Agents 通过检查点免费获得情景记忆：每次对话都作为检查点线程持久保存。为了使过去的对话可搜索，可以将线程搜索包装在一个工具中。user_id 从运行时上下文中获取，而不是作为参数传递： 
from langgraph_sdk import get_client
from langchain.tools import tool
from langgraph.config import get_config

client = get_client(url="<DEPLOYMENT_URL>")


@tool
async def search_past_conversations(query: str) -> str:
    """搜索过去的对话以获取相关上下文。"""
    config = get_config()
    user_id = config["metadata"]["user_id"]
    threads = await client.threads.search(
        metadata={"user_id": user_id},
        limit=5,
    )
    results = []
    for thread in threads:
        history = await client.threads.get_history(thread_id=thread["thread_id"])
        results.append(history)
    return str(results)
你可以通过调整元数据过滤器来按用户或组织限定线程搜索范围： 
# 搜索特定用户的对话
threads = await client.threads.search(
    metadata={"user_id": user_id},
    limit=5,
)

# 搜索整个组织的对话
threads = await client.threads.search(
    metadata={"org_id": org_id},
    limit=5,
)
这对于执行复杂、多步骤任务的智能体非常有用。例如，一个编码智能体可以回顾过去的调试会话，直接跳转到可能的根本原因。

​
技能作为程序性记忆

技能是程序性记忆的一种形式：可重用的指令，告诉智能体如何执行任务。与语义记忆（事实）或情景记忆（经历）不同，程序性记忆编码了智能体可以按需应用的逐步能力。 技能可以是：
  • 只读（开发者定义）：开发者编写技能，智能体使用它们但不能修改。这是最常见的模式。
  • 读写（智能体学习）：智能体根据经验创建和更新技能。当智能体拥有记忆的写入权限时，它也可以写入其技能目录。使用策略钩子来控制哪些路径可写。
技能通常是智能体作用域的（所有用户共享），但如果存储在用户命名空间的后端中，也可以是用户作用域的。 在 Deep Agents 中，通过 skills= 参数传递技能。技能是按需加载的，而不是注入到每个提示词中，从而在需要能力之前保持上下文简洁： 
from deepagents import create_deep_agent

agent = create_deep_agent(
    memory=["/memories/AGENTS.md"],
    skills=["/skills/"],
    # ...后端配置
)
有关定义、组织和使用技能的完整指南，请参阅技能文档。

​
组织级记忆

组织级记忆遵循与用户作用域记忆相同的模式，但使用共享命名空间而不是每个用户的命名空间。将其用于应适用于所有用户和智能体的策略或知识。 组织记忆通常是只读的，以防止通过共享状态进行提示词注入。有关详细信息，请参阅只读与可写记忆。 
from deepagents import create_deep_agent
from deepagents.backends import CompositeBackend, StateBackend, StoreBackend

agent = create_deep_agent(
    memory=[
        "/memories/preferences.md",
        "/policies/compliance.md",
    ],
    backend=CompositeBackend(
        default=StateBackend(),
        routes={
            "/memories/": StoreBackend(
                namespace=lambda ctx: (ctx.runtime.context.user_id,),
            ),
            "/policies/": StoreBackend(
                namespace=lambda ctx: (),
            ),
        },
    ),
)
从你的应用程序代码填充组织记忆： 
from langgraph_sdk import get_client
from deepagents.backends.utils import create_file_data

client = get_client(url="<DEPLOYMENT_URL>")

await client.store.put_item(
    (),
    "/compliance.md",
    create_file_data("""## 合规政策
- 绝不披露内部定价
- 财务建议必须包含免责声明
"""),
)
使用策略钩子来强制执行组织级记忆为只读。

​
后台整合

默认情况下，智能体在对话期间写入记忆（热路径）。另一种方法是在对话之间作为后台任务处理记忆，有时称为休眠时间计算。一个独立的深度智能体审查最近的对话，提取关键事实，并将其与现有记忆合并。
方法优点缺点
热路径（对话期间）记忆立即可用，对用户透明增加延迟，智能体必须多任务处理
后台（对话之间）无用户侧延迟，可以跨多个对话综合记忆直到下次对话才可用，需要第二个智能体
对于大多数应用，热路径已足够。当你需要减少延迟或提高跨多次对话的记忆质量时，可以添加后台整合。 所有三种方法都部署一个整合智能体与你的主智能体一起运行：一个深度智能体，读取对话历史，提取关键事实，并将其合并到记忆存储中。
触发器何时运行最适合
Cron固定计划（例如，每6小时）跨多次对话批处理，综合趋势
计划运行在同一线程上延迟后运行客户端控制整合触发时间的简单设置
所有三种方法都使用相同的整合智能体和部署配置。定义一次，然后选择触发器。

​
整合智能体

整合智能体读取最近的对话历史，并将关键事实合并到记忆存储中。在 langgraph.json 中将其与你的主智能体一起注册：
consolidation_agent.py
from datetime import datetime, timedelta, timezone

from deepagents import create_deep_agent
from langchain.tools import tool
from langgraph.config import get_config
from langgraph_sdk import get_client

sdk_client = get_client(url="<DEPLOYMENT_URL>")


@tool
async def search_recent_conversations(query: str) -> str:
    """搜索该用户最近6小时内更新的对话。"""
    config = get_config()
    user_id = config["configurable"]["langgraph_auth_user_id"]

    since = datetime.now(timezone.utc) - timedelta(hours=6)
    threads = await sdk_client.threads.search(
        metadata={"user_id": user_id},
        updated_after=since.isoformat(),
        limit=20,
    )
    conversations = []
    for thread in threads:
        history = await sdk_client.threads.get_history(
            thread_id=thread["thread_id"]
        )
        conversations.append(history["values"]["messages"])
    return str(conversations)


agent = create_deep_agent(
    model="claude-sonnet-4-6",
    system_prompt="""审查最近的对话并更新用户的记忆文件。
合并新事实，删除过时信息，并保持简洁。""",
    tools=[search_recent_conversations],
)
langgraph.json
{
  "dependencies": ["."],
  "graphs": {
    "agent": "./agent.py:agent",
    "consolidation_agent": "./consolidation_agent.py:agent"
  },
  "env": ".env"
}

​
Cron

一个cron 任务按固定计划运行整合智能体。智能体搜索所有最近的对话，并将其综合到记忆中。 使用 cron 任务调度整合智能体： 
from langgraph_sdk import get_client

client = get_client(url="<DEPLOYMENT_URL>")

cron_job = await client.crons.create(
    assistant_id="consolidation_agent",
    schedule="0 */6 * * *",
    input={"messages": [{"role": "user", "content": "整合最近的记忆。"}]},
)
所有 cron 计划都基于 UTC 时间解释。有关管理和删除 cron 任务的详细信息，请参阅cron 任务。

​
计划运行

使用 after_seconds 参数在每次对话后调度运行。这是活动驱动的：只有当用户活跃时才会触发整合。传递相同的 thread_id，以便整合智能体可以访问对话上下文。 延迟为对话完成提供了时间（用户可能会发送后续消息），因此整合智能体可以看到完整的交流。 如果用户在延迟期间发送了另一条消息，新运行的 multitask_strategy 控制待处理的整合运行会发生什么。在新运行上使用 rollback 删除过时的整合运行，然后在下次响应后调度一个新的整合运行： 
from langgraph_sdk import get_client

client = get_client(url="<DEPLOYMENT_URL>")

# 在对话后30分钟调度整合
await client.runs.create(
    thread_id=thread["thread_id"],
    assistant_id="consolidation_agent",
    input={"messages": [{"role": "user", "content": "整合最近的记忆。"}]},
    after_seconds=1800,
)

# 如果用户发送另一条消息，在新运行上使用 rollback
# 在开始前删除待处理的整合运行
await client.runs.stream(
    thread_id=thread["thread_id"],
    assistant_id="agent",
    input={"messages": [{"role": "user", "content": new_message}]},
    multitask_strategy="rollback",
)
有关 multitask_strategy 如何控制同一线程上并发运行的行为的详细信息，请参阅双重发送。 有关部署具有后台进程的智能体的更多信息，请参阅投入生产。

​
只读与可写记忆

默认情况下，智能体可以读取和写入记忆文件。对于共享状态，如组织策略或合规规则，你可能希望将记忆设置为只读，以便智能体可以引用但不能修改它。这可以防止通过共享记忆进行提示词注入，并确保只有你的应用程序代码控制文件内容。
权限使用场景工作原理
读写（默认）用户偏好、智能体自我改进、学习的技能智能体通过 edit_file 工具更新文件
只读组织策略、合规规则、共享知识库、开发者定义的技能通过应用程序代码或存储 API 填充。使用策略钩子阻止智能体写入。
安全考虑： 如果一个用户可以写入另一个用户读取的记忆，恶意用户可能会向共享状态注入指令。为了缓解这种情况：
  • 默认使用用户作用域 (user_id)，除非有特定原因需要共享
  • 对共享策略使用只读记忆（通过应用程序代码填充，而不是智能体）
  • 在智能体写入敏感路径之前添加人在回路验证。使用中断要求人工批准对敏感路径的写入。
要强制执行只读记忆，请在后端使用策略钩子来拒绝对特定路径的写入操作。

​
并发写入

多个线程可以并行写入记忆，但对同一文件的并发写入可能导致最后写入胜出的冲突。对于用户作用域记忆，这种情况很少见，因为用户通常一次只有一个活跃对话。对于智能体作用域或组织作用域记忆，可以考虑使用后台整合来序列化写入，或者将记忆结构化为每个主题的单独文件以减少争用。 实际上，如果由于冲突导致写入失败，LLM 通常足够智能，能够重试或优雅地恢复，因此单次丢失的写入并不致命。

​
同一部署中的多个智能体

要在共享部署中为每个智能体提供其专属的记忆，请将 assistant_id 添加到命名空间： 
StoreBackend(
    namespace=lambda ctx: (
        get_config()["metadata"]["assistant_id"],
        ctx.runtime.context.user_id,
    ),
)
如果只需要按智能体隔离而不需要按用户限定作用域，可以单独使用 (assistant_id,)。
使用 LangSmith 追踪来审计智能体写入记忆的内容。每次文件写入都会在追踪中显示为工具调用。
Edit this page on GitHub or file an issue.
Connect these docs to Claude, VSCode, and more via MCP for real-time answers.