记忆（Memory）

为什么需要它

你有没有试过让 Agent 记住用户上次说过的话？

开始之前

工作原理

三步走：指向记忆文件 → Agent 读取 → Agent 更新

import { createDeepAgent, CompositeBackend, StateBackend, StoreBackend } from "deepagents";

const agent = createDeepAgent({
  memory: ["/memories/AGENTS.md"],  // Agent 启动时加载到系统提示的记忆文件
  skills: ["/skills/"],             // 按需加载的技能目录
  backend: new CompositeBackend(
    new StateBackend(),              // 默认后端用于临时状态
    {
      // 记忆文件路由到 StoreBackend，支持持久化
      "/memories/": new StoreBackend({
        namespace: (rt) => [rt.serverInfo.assistantId],  // 按 Agent ID 隔离
      }),
      // 技能文件也用 StoreBackend，支持跨线程共享
      "/skills/": new StoreBackend({
        namespace: (rt) => [rt.serverInfo.assistantId],  // 同一 Agent 共享
      }),
    },
  ),
});

记忆分类

短期记忆管"这一次对话"，长期记忆管"所有对话"

作用域

通过命名空间控制记忆的"可见范围"——谁能看到什么

Deep Agents 通过后端的命名空间来控制记忆的作用域。不同的命名空间策略决定了记忆的共享范围：

Agent 级别

赋予 Agent 自己的持久化身份——它随时间不断演进

Agent 级别记忆在所有用户之间共享，因此 Agent 会通过每一次对话积累自己的个性、知识和偏好。随着与用户的交互，它会不断深化专业知识、优化方法，并记住哪些做法有效。命名空间设为 (assistant_id,)，意味着该 Agent 的每一次对话都读写同一个记忆文件。当拥有写入权限时，它还可以学习和更新 Skill。

import { createDeepAgent, CompositeBackend, StateBackend, StoreBackend } from "deepagents";

const agent = createDeepAgent({
  memory: ["/memories/AGENTS.md"],
  skills: ["/skills/"],
  backend: new CompositeBackend(
    new StateBackend(),
    {
      "/memories/": new StoreBackend({
        // assistantId 作为命名空间，所有用户共享同一份记忆
        namespace: (rt) => [rt.serverInfo.assistantId],
      }),
      "/skills/": new StoreBackend({
        // 同理，所有用户共享同一份技能
        namespace: (rt) => [rt.serverInfo.assistantId],
      }),
    },
  ),
});

import { InMemoryStore } from "@langchain/langgraph";
import { createFileData } from "deepagents";

const store = new InMemoryStore();

// 向 Store 中写入初始记忆
await store.put(
  ["my-agent"],
  "/memories/AGENTS.md",
  createFileData(`## Response style
- Keep responses concise
- Use code examples where possible
`),
);

// 线程 1：Agent 学习偏好
const config1 = { configurable: {
  thread_id: uuidv4()
}};
await agent.invoke({
  messages: [{
    role: "user",
    content: "I prefer detailed explanations."
  }],
}, config1);

// 线程 2：Agent 记住了偏好
const config2 = { configurable: {
  thread_id: uuidv4()
}};
await agent.invoke({
  messages: [{
    role: "user",
    content: "Explain transformers."
  }],
}, config2);

用户级别

为每个用户提供独立的记忆文件——个性化服务的基石

命名空间设为 (user_id,)，每个用户获得一份隔离的记忆文件副本。用户 A 的偏好永远不会泄露到用户 B 的对话中。

import { createDeepAgent, CompositeBackend, StateBackend, StoreBackend } from "deepagents";

const agent = createDeepAgent({
  memory: ["/memories/preferences.md"],
  skills: ["/skills/"],
  backend: new CompositeBackend(
    new StateBackend(),
    {
      "/memories/": new StoreBackend({
        // user.identity 作为命名空间，每个用户独立一份记忆
        namespace: (rt) => [rt.serverInfo.user.identity],
      }),
      "/skills/": new StoreBackend({
        // 同理，每个用户独立一份技能
        namespace: (rt) => [rt.serverInfo.user.identity],
      }),
    },
  ),
});

await store.put(
  ["user-alice"],
  "/memories/preferences.md",
  createFileData(`## Preferences
- Likes concise bullet points
- Prefers Python examples
`)
);

await store.put(
  ["user-bob"],
  "/memories/preferences.md",
  createFileData(`## Preferences
- Likes detailed explanations
- Prefers TypeScript examples
`)
);

高级维度

记忆不只是"存取"——六个维度决定你的记忆策略

情景记忆

让 Agent 回忆"过去是怎么解决问题的"——不只是学到了什么

情景记忆存储完整的对话上下文：发生了什么、顺序如何、结果怎样。Deep Agents 已通过 Checkpoint 机制自动保存每一段对话。要让过去的对话可搜索，可以把线程搜索封装为一个工具：

import { Client } from "@langchain/langgraph-sdk";
import { tool } from "@langchain/core/tools";

const client = new Client({ apiUrl: "" });

const searchPastConversations = tool(
  async ({ query }, runtime) => {
    // 从运行时上下文获取用户 ID，而非作为参数传入——防止用户伪造身份
    const userId = runtime.serverInfo.user.identity;
    // 按用户 ID 搜索历史对话线程，最多返回 5 条
    const threads = await client.threads.search({
      metadata: { userId },
      limit: 5,
    });
    const results = [];
    for (const thread of threads) {
      const history = await client.threads.getHistory(thread.threadId);
      results.push(history);
    }
    return JSON.stringify(results);
  },
  {
    name: "search_past_conversations",
    description: "Search past conversations for relevant context.",
  }
);

const userThreads = await client.threads.search({
  metadata: { userId },
  limit: 5,
});

const orgThreads = await client.threads.search({
  metadata: { orgId },
  limit: 5,
});

组织级记忆

跨用户共享的策略和知识——通常是只读的

组织级别记忆使用组织范围的命名空间，用于对组织内所有用户和 Agent 生效的策略或知识。它通常是只读的，以防止提示注入。

const agent = createDeepAgent({
  memory: [
    "/memories/preferences.md",  // 用户级：按用户隔离，可读写
    "/policies/compliance.md",   // 组织级：所有人共享，通常只读
  ],
  backend: new CompositeBackend(
    new StateBackend(),
    {
      // 用户偏好：按用户身份隔离存储
      "/memories/": new StoreBackend({
        namespace: (rt) => [rt.serverInfo.user.identity],
      }),
      // 组织策略：按组织 ID 共享，通过权限配置为只读
      "/policies/": new StoreBackend({
        namespace: (rt) => [rt.context.orgId],
      }),
    },
  ),
});

import { Client } from "@langchain/langgraph-sdk";
import { createFileData } from "deepagents";

const client = new Client({
  apiUrl: ""
});

await client.store.putItem(
  [orgId],
  "/compliance.md",
  createFileData(`## Compliance policies
- Never disclose internal pricing
- Always include disclaimers
  on financial advice
`),
);

后台整合

让 Agent 在"空闲时"回顾对话、提取关键事实——零延迟记忆升级

默认方式是热路径（对话中即时写入记忆）。另一种方式是后台整合——有时也被称为休眠期计算（sleep time compute）：一个独立的 Deep Agent 在对话之间审查最近的对话，提取关键事实并合并到记忆中。

整合 Agent

一个独立的 Deep Agent——读取最近对话、提取事实、合并到记忆

// src/consolidation-agent.ts
import { createDeepAgent } from "deepagents";
import { Client } from "@langchain/langgraph-sdk";
import { tool } from "@langchain/core/tools";

const sdkClient = new Client({ apiUrl: "" });

const searchRecentConversations = tool(
  async ({ query }, runtime) => {
    const userId = runtime.serverInfo.user.identity;
    // 回溯 6 小时内的对话，与 Cron 间隔匹配
    const since = new Date(Date.now() - 6 * 60 * 60 * 1000).toISOString();
    const threads = await sdkClient.threads.search({
      metadata: { userId },       // 按用户筛选
      updatedAfter: since,         // 只查找最近 6 小时内更新的线程
      limit: 20,                   // 最多获取 20 条
    });
    // 遍历每个线程，获取完整对话历史
    const conversations = [];
    for (const thread of threads) {
      const history = await sdkClient.threads.getHistory(thread.threadId);
      conversations.push(history.values.messages);
    }
    return JSON.stringify(conversations);
  },
  {
    name: "search_recent_conversations",
    description: "Search this user's conversations updated in the last 6 hours.",
  }
);

const agent = createDeepAgent({
  model: "google-genai:gemini-3.1-pro-preview",
  systemPrompt: `Review recent conversations and update the user's memory file.
Merge new facts, remove outdated information, and keep it concise.`,
  tools: [searchRecentConversations],
});

export { agent };

{
  "dependencies": ["."],
  "graphs": {
    "agent": "./src/agent.ts:agent",
    "consolidation_agent":
      "./src/consolidation-agent.ts:agent"
  },
  "env": ".env"
}

import { Client } from "@langchain/langgraph-sdk";

const client = new Client({
  apiUrl: ""
});

const cronJob = await client.crons.create(
  "consolidation_agent",
  {
    schedule: "0 */6 * * *",  // 每 6 小时
    input: { messages: [{
      role: "user",
      content: "Consolidate recent memories."
    }] },
  },
);

并发与隔离

多线程写入和多 Agent 共存的注意事项

new StoreBackend({
  // 多维度命名空间：先按 Agent 再按用户隔离
  // 避免不同 Agent 的记忆互相污染
  namespace: (rt) => [
    rt.serverInfo.assistantId,
    rt.serverInfo.user.identity,
  ],
})

动手练习

设计一个带记忆的技术支持 Agent——综合运用作用域、情景记忆和后台整合

现在轮到你了。停下来，思考如何用 Deep Agents 构建一个带持久化记忆的技术支持 Agent。需求如下：

智能体应该：
1. 记住每个用户的偏好（语言、回答风格、常见问题）
2. 搜索过去的对话历史来回答重复问题
3. 从每次对话中学习新的解决方案
4. 每个用户的记忆完全隔离
5. 组织级的合规策略不可被 Agent 修改
6. 每 4 小时自动整合最近的对话

参考答案

一种可行的设计方案——三级作用域 + 后台整合

import { v4 as uuidv4 } from "uuid";
import { createDeepAgent, CompositeBackend, StateBackend, StoreBackend, createFileData } from "deepagents";
import { InMemoryStore } from "@langchain/langgraph";

const store = new InMemoryStore();

// 初始化组织级只读策略（由应用代码写入，Agent 不可修改）
await store.put(
  ["my-org"],                                   // 组织级命名空间
  "/policies/compliance.md",                     // 文件路径
  createFileData(`## Support Policies
- Never share user data between accounts
- Always include SLA timelines in responses
- Escalate billing issues to human agents
`),
);

const agent = createDeepAgent({
  memory: [
    "/memories/preferences.md",   // 用户级：按用户隔离，可读写
    "/policies/compliance.md",    // 组织级：只读策略，需配合权限配置
  ],
  backend: new CompositeBackend(
    new StateBackend(),
    {
      // 用户偏好：按用户身份隔离
      "/memories/": new StoreBackend({
        namespace: (rt) => [rt.serverInfo.user.identity],
      }),
      // 组织策略：按组织 ID 共享
      "/policies/": new StoreBackend({
        namespace: (rt) => [rt.context.orgId],
      }),
    },
  ),
  store,
});

// Cron：每 4 小时运行
await client.crons.create(
  "consolidation_agent",
  {
    schedule: "0 */4 * * *",
    input: { messages: [{
      role: "user",
      content: "Consolidate."
    }] },
  },
);

// 回溯窗口：4 小时（与 Cron 匹配）
const since = new Date(
  Date.now() - 4 * 60 * 60 * 1000
);

本章回顾

到这里，你已经掌握了 Deep Agents 记忆系统的完整用法

延伸阅读