短期记忆

概览

记忆是一个记录先前交互信息的系统。对于 AI 智能体而言，记忆至关重要，因为它能让智能体回想起之前的交互、从反馈中学习并适应用户偏好。随着智能体处理的复杂任务和用户交互次数的增加，这种能力对于提高效率和用户满意度变得必不可少。短期记忆可以让您的应用程序记住单个线程或对话内的先前交互。

线程将多次交互组织在一次会话中，类似于电子邮件将消息归类在同一个对话中的方式。

对话历史是短期记忆最常见的形式。长对话对当今的大型语言模型 (LLM) 构成了挑战；完整的历史记录可能无法装入 LLM 的上下文窗口，从而导致上下文丢失或错误。即使您的模型支持完整的上下文长度，大多数 LLM 在处理长上下文时表现仍然不佳。它们会因为陈旧或无关的内容而“分心”，同时还会遭遇响应速度变慢和成本增加的问题。聊天模型使用消息来接收上下文，这些消息包括指令（系统消息）和输入（人类消息）。在聊天应用程序中，消息在人类输入和模型响应之间交替进行，导致消息列表随时间推移而变长。由于上下文窗口是有限的，许多应用程序可以通过使用一些技术来删除或“遗忘”过时的信息而受益。

需要跨对话记住信息？请使用长期记忆来存储和检索跨不同线程和会话的用户特定或应用程序级数据。

用法

要为智能体添加短期记忆（线程级持久化），您需要在创建智能体时指定一个 checkpointer（检查点）。

LangChain 的智能体将短期记忆作为智能体状态的一部分进行管理。通过将这些信息存储在图的状态中，智能体可以在保持不同线程间隔离的同时，访问特定对话的完整上下文。状态通过检查点机制持久化到数据库（或内存）中，以便线程可以随时恢复。短期记忆会在调用智能体或完成某一步骤（如工具调用）时更新，并在每一步开始时读取状态。

import { createAgent } from "langchain";
import { MemorySaver } from "@langchain/langgraph";

const checkpointer = new MemorySaver();

const agent = createAgent({
    model: "claude-sonnet-4-6",
    tools: [],
    checkpointer,
});

await agent.invoke(
    { messages: [{ role: "user", content: "hi! i am Bob" }] },
    { configurable: { thread_id: "1" } }
);

生产环境

在生产中，使用由数据库支持的检查点器

import { PostgresSaver } from "@langchain/langgraph-checkpoint-postgres";

const DB_URI = "postgresql://postgres:postgres@localhost:5442/postgres?sslmode=disable";
const checkpointer = PostgresSaver.fromConnString(DB_URI);

有关包括 SQLite、Postgres 和 Azure Cosmos DB 在内的更多检查点选项，请参阅持久化文档中的检查点库列表。

自定义智能体记忆

您可以通过创建带有状态架构的自定义中间件来扩展智能体状态。自定义状态架构可以使用中间件中的 stateSchema 参数传递。建议使用 StateSchema 类进行状态定义（也支持纯 Zod 对象）。

import { createAgent, createMiddleware } from "langchain";
import { StateSchema, MemorySaver } from "@langchain/langgraph";
import * as z from "zod";

const CustomState = new StateSchema({
    userId: z.string(),
    preferences: z.record(z.string(), z.any()),
});

const stateExtensionMiddleware = createMiddleware({
    name: "StateExtension",
    stateSchema: CustomState,
});

const checkpointer = new MemorySaver();
const agent = createAgent({
    model: "gpt-5.4",
    tools: [],
    middleware: [stateExtensionMiddleware],
    checkpointer,
});

// Custom state can be passed in invoke
const result = await agent.invoke({
    messages: [{ role: "user", content: "Hello" }],
    userId: "user_123",
    preferences: { theme: "dark" },
});

常见模式

启用短期记忆后，长对话可能会超过 LLM 的上下文窗口。常见的解决方案包括：

截断消息

删除前 N 条或后 N 条消息（在调用 LLM 之前）

删除消息

从 LangGraph 状态中永久删除消息

总结消息

总结历史中的早期消息并用摘要替换它们

自定义策略

自定义策略（例如，消息过滤等）

这使得代理可以跟踪对话，而不会超出 LLM 的上下文窗口。

截断消息

大多数 LLM 都有一个最大支持的上下文窗口（以 token 为单位）。决定何时截断消息的一种方法是计算消息历史中的 token 数量，并在接近限制时进行截断。如果您使用的是 LangChain，可以使用截断消息工具，指定要保留的列表条目数，以及用于处理边界的 strategy（例如保留最后的 maxTokens）。要在智能体中截断消息历史，请使用带有 beforeModel 钩子的 createMiddleware：

import { RemoveMessage } from "@langchain/core/messages";
import { createAgent, createMiddleware } from "langchain";
import { MemorySaver, REMOVE_ALL_MESSAGES } from "@langchain/langgraph";

const trimMessages = createMiddleware({
  name: "TrimMessages",
  beforeModel: (state) => {
    const messages = state.messages;

    if (messages.length <= 3) {
      return; // No changes needed
    }

    const firstMsg = messages[0];
    const recentMessages =
      messages.length % 2 === 0 ? messages.slice(-3) : messages.slice(-4);
    const newMessages = [firstMsg, ...recentMessages];

    return {
      messages: [
        new RemoveMessage({ id: REMOVE_ALL_MESSAGES }),
        ...newMessages,
      ],
    };
  },
});

const checkpointer = new MemorySaver();
const agent = createAgent({
  model: "gpt-5.4",
  tools: [],
  middleware: [trimMessages],
  checkpointer,
});

删除消息

您可以从图状态中删除消息来管理消息历史。当您想要删除特定消息或清除整个消息历史时，这非常有用。要从图状态中删除消息，可以使用 RemoveMessage。为了让 RemoveMessage 起作用，您需要使用一个带有 messagesStateReducer 归约器 (reducer) 的状态键，例如 MessagesValue。要删除特定消息：

import { RemoveMessage } from "@langchain/core/messages";

const deleteMessages = (state) => {
    const messages = state.messages;
    if (messages.length > 2) {
        // remove the earliest two messages
        return {
        messages: messages
            .slice(0, 2)
            .map((m) => new RemoveMessage({ id: m.id })),
        };
    }
};

删除消息时，请确保生成的消息历史有效。检查你正在使用的 LLM 提供商的限制。例如：

某些提供程序期望消息历史记录以 user 消息开头
大多数提供程序要求带有工具调用的 assistant 消息后跟相应的 tool 结果消息。

import { RemoveMessage } from "@langchain/core/messages";
import { createAgent, createMiddleware } from "langchain";
import { MemorySaver } from "@langchain/langgraph";

const deleteOldMessages = createMiddleware({
  name: "DeleteOldMessages",
  afterModel: (state) => {
    const messages = state.messages;
    if (messages.length > 2) {
      // remove the earliest two messages
      return {
        messages: messages
          .slice(0, 2)
          .map((m) => new RemoveMessage({ id: m.id! })),
      };
    }
    return;
  },
});

const agent = createAgent({
  model: "gpt-5.4",
  tools: [],
  systemPrompt: "Please be concise and to the point.",
  middleware: [deleteOldMessages],
  checkpointer: new MemorySaver(),
});

const config = { configurable: { thread_id: "1" } };

const streamA = await agent.stream(
  { messages: [{ role: "user", content: "hi! I'm bob" }] },
  { ...config, streamMode: "values" }
);
for await (const event of streamA) {
  const messageDetails = event.messages.map((message) => [
    message.getType(),
    message.content,
  ]);
  console.log(messageDetails);
}

const streamB = await agent.stream(
  {
    messages: [{ role: "user", content: "what's my name?" }],
  },
  { ...config, streamMode: "values" }
);
for await (const event of streamB) {
  const messageDetails = event.messages.map((message) => [
    message.getType(),
    message.content,
  ]);
  console.log(messageDetails);
}

[[ "human", "hi! I'm bob" ]]
[[ "human", "hi! I'm bob" ], [ "ai", "Hello, Bob! How can I assist you today?" ]]
[[ "human", "hi! I'm bob" ], [ "ai", "Hello, Bob! How can I assist you today?" ]]
[[ "human", "hi! I'm bob" ], [ "ai", "Hello, Bob! How can I assist you today" ], ["human", "what's my name?" ]]
[[ "human", "hi! I'm bob" ], [ "ai", "Hello, Bob! How can I assist you today?" ], ["human", "what's my name?"], [ "ai", "Your name is Bob, as you mentioned. How can I help you further?" ]]
[[ "human", "what's my name?" ], [ "ai", "Your name is Bob, as you mentioned. How can I help you further?" ]]

总结消息

如上所示，修剪或删除消息的问题在于，由于删除了消息队列，您可能会丢失信息。正因如此，一些应用程序从使用聊天模型总结消息历史的更复杂方法中受益。

要在智能体中总结消息历史，请使用内置的 summarizationMiddleware：

import { createAgent, summarizationMiddleware } from "langchain";
import { MemorySaver } from "@langchain/langgraph";

const checkpointer = new MemorySaver();

const agent = createAgent({
  model: "gpt-5.4",
  tools: [],
  middleware: [
    summarizationMiddleware({
      model: "gpt-5.4-mini",
      trigger: { tokens: 4000 },
      keep: { messages: 20 },
    }),
  ],
  checkpointer,
});

const config = { configurable: { thread_id: "1" } };
await agent.invoke({ messages: "hi, my name is bob" }, config);
await agent.invoke({ messages: "write a short poem about cats" }, config);
await agent.invoke({ messages: "now do the same but for dogs" }, config);
const finalResponse = await agent.invoke({ messages: "what's my name?" }, config);

console.log(finalResponse.messages.at(-1)?.content);
// Your name is Bob!

有关更多配置选项，请参阅 summarizationMiddleware。

访问记忆

您可以通过多种方式访问和修改智能体的短期记忆（状态）：

工具

在工具中读取短期记忆

使用 runtime 参数（类型为 ToolRuntime）在工具中访问短期记忆（状态）。 runtime 参数在工具签名中是隐藏的（因此模型无法看到它），但工具可以通过它访问状态。

import { createAgent, tool, type ToolRuntime } from "langchain";
import { StateSchema } from "@langchain/langgraph";
import * as z from "zod";

const CustomState = new StateSchema({
  userId: z.string(),
});

const getUserInfo = tool(
  async (_, config: ToolRuntime<typeof CustomState.State>) => {
    const userId = config.state.userId;
    return userId === "user_123" ? "John Doe" : "Unknown User";
  },
  {
    name: "get_user_info",
    description: "Get user info",
    schema: z.object({}),
  }
);

const agent = createAgent({
  model: "gpt-5-nano",
  tools: [getUserInfo],
  stateSchema: CustomState,
});

const result = await agent.invoke(
  {
    messages: [{ role: "user", content: "what's my name?" }],
    userId: "user_123",
  },
  {
    context: {},
  }
);

console.log(result.messages.at(-1)?.content);
// Outputs: "Your name is John Doe."

通过工具写入短期记忆

要在执行期间修改智能体的短期记忆（状态），您可以直接从工具返回状态更新。这对于持久化中间结果或使后续工具或提示词能够访问信息非常有用。

import { tool, createAgent, ToolMessage, type ToolRuntime } from "langchain";
import { Command, StateSchema } from "@langchain/langgraph";
import * as z from "zod";

const CustomState = new StateSchema({
  userId: z.string().optional(),
});

const updateUserInfo = tool(
  async (_, config: ToolRuntime<typeof CustomState.State>) => {
    const userId = config.state.userId;
    const name = userId === "user_123" ? "John Smith" : "Unknown user";
    return new Command({
      update: {
        userName: name,
        // update the message history
        messages: [
          new ToolMessage({
            content: "Successfully looked up user information",
            tool_call_id: config.toolCall?.id ?? "",
          }),
        ],
      },
    });
  },
  {
    name: "update_user_info",
    description: "Look up and update user info.",
    schema: z.object({}),
  }
);

const greet = tool(
  async (_, config) => {
    const userName = config.context?.userName;
    return `Hello ${userName}!`;
  },
  {
    name: "greet",
    description: "Use this to greet the user once you found their info.",
    schema: z.object({}),
  }
);

const agent = createAgent({
  model: "openai:gpt-5-mini",
  tools: [updateUserInfo, greet],
  stateSchema: CustomState,
});

const result = await agent.invoke({
  messages: [{ role: "user", content: "greet the user" }],
  userId: "user_123",
});

console.log(result.messages.at(-1)?.content);
// Output: "Hello! I’m here to help — what would you like to do today?"

提示

在中间件中访问短期记忆（状态），以便根据对话历史或自定义状态字段创建动态提示词。

import * as z from "zod";
import { createAgent, tool, dynamicSystemPromptMiddleware } from "langchain";

const contextSchema = z.object({
  userName: z.string(),
});
type ContextSchema = z.infer<typeof contextSchema>;

const getWeather = tool(
  async ({ city }) => {
    return `The weather in ${city} is always sunny!`;
  },
  {
    name: "get_weather",
    description: "Get user info",
    schema: z.object({
      city: z.string(),
    }),
  }
);

const agent = createAgent({
  model: "gpt-5-nano",
  tools: [getWeather],
  contextSchema,
  middleware: [
    dynamicSystemPromptMiddleware<ContextSchema>((_, config) => {
      return `You are a helpful assistant. Address the user as ${config.context?.userName}.`;
    }),
  ],
});

const result = await agent.invoke(
  {
    messages: [{ role: "user", content: "What is the weather in SF?" }],
  },
  {
    context: {
      userName: "John Smith",
    },
  }
);

for (const message of result.messages) {
  console.log(message);
}
/**
 * HumanMessage {
 *   "content": "What is the weather in SF?",
 *   // ...
 * }
 * AIMessage {
 *   // ...
 *   "tool_calls": [
 *     {
 *       "name": "get_weather",
 *       "args": {
 *         "city": "San Francisco"
 *       },
 *       "type": "tool_call",
 *       "id": "call_tCidbv0apTpQpEWb3O2zQ4Yx"
 *     }
 *   ],
 *   // ...
 * }
 * ToolMessage {
 *   "content": "The weather in San Francisco is always sunny!",
 *   "tool_call_id": "call_tCidbv0apTpQpEWb3O2zQ4Yx"
 *   // ...
 * }
 * AIMessage {
 *   "content": "John Smith, here's the latest: The weather in San Francisco is always sunny!\n\nIf you'd like more details (temperature, wind, humidity) or a forecast for the next few days, I can pull that up. What would you like?",
 *   // ...
 * }
 */

模型执行前

import { RemoveMessage } from "@langchain/core/messages";
import { createAgent, createMiddleware, trimMessages } from "langchain";
import { MemorySaver } from "@langchain/langgraph";
import { REMOVE_ALL_MESSAGES } from "@langchain/langgraph";

const trimMessageHistory = createMiddleware({
  name: "TrimMessages",
  beforeModel: async (state) => {
    const trimmed = await trimMessages(state.messages, {
      maxTokens: 384,
      strategy: "last",
      startOn: "human",
      endOn: ["human", "tool"],
      tokenCounter: (msgs) => msgs.length,
    });
    return {
      messages: [new RemoveMessage({ id: REMOVE_ALL_MESSAGES }), ...trimmed],
    };
  },
});

const checkpointer = new MemorySaver();
const agent = createAgent({
  model: "gpt-5-nano",
  tools: [],
  middleware: [trimMessageHistory],
  checkpointer,
});

模型执行后

import { RemoveMessage } from "@langchain/core/messages";
import { createAgent, createMiddleware } from "langchain";
import { REMOVE_ALL_MESSAGES } from "@langchain/langgraph";

const validateResponse = createMiddleware({
  name: "ValidateResponse",
  afterModel: (state) => {
    const lastMessage = state.messages.at(-1)?.content;
    if (
      typeof lastMessage === "string" &&
      lastMessage.toLowerCase().includes("confidential")
    ) {
      return {
        messages: [
          new RemoveMessage({ id: REMOVE_ALL_MESSAGES }),
        ],
      };
    }
    return;
  },
});

const agent = createAgent({
  model: "gpt-5-nano",
  tools: [],
  middleware: [validateResponse],
});

将这些文档连接到 Claude、VSCode 等，以获得实时答案。

在 GitHub 上编辑此页面或提交问题。

入门

核心组件

中间件

前端

高级用法

Agent 开发

使用 LangSmith 部署

概览

用法

生产环境

自定义智能体记忆

常见模式

截断消息

删除消息

总结消息

自定义策略

截断消息

删除消息

总结消息

访问记忆

工具

在工具中读取短期记忆

通过工具写入短期记忆

提示

模型执行前

模型执行后

入门

核心组件

中间件

前端

高级用法

Agent 开发

使用 LangSmith 部署

文档索引

​概览

​用法

​生产环境

​自定义智能体记忆

​常见模式

截断消息

删除消息

总结消息

自定义策略

​截断消息

​删除消息

​总结消息

​访问记忆

​工具

​在工具中读取短期记忆

​通过工具写入短期记忆

​提示

​模型执行前

​模型执行后

概览

用法

生产环境

自定义智能体记忆

常见模式

截断消息

删除消息

总结消息

访问记忆

工具

在工具中读取短期记忆

通过工具写入短期记忆

提示

模型执行前

模型执行后