存储 - Docs by LangChain中文

存储允许智能体跨线程持久化信息，包括用户偏好、积累的知识以及应超越单次对话而存活的事实。与检查点保存器将完整图状态保存到单个线程不同，存储持有可从任何线程访问的任意键值数据。共享状态模型

Agent Server 自动处理存储 使用 Agent Server 时，您无需手动实现或配置存储。API 会在后台为您处理所有存储基础设施。

InMemoryStore 适用于开发和测试。对于生产环境，请使用 PostgresStore、MongoDBStore 或 RedisStore 等持久化存储。所有实现都扩展了 BaseStore，这是节点函数签名中应使用的类型注解。

基本用法

以下代码片段展示了独立使用 InMemoryStore，而不使用 LangGraph：

import { MemoryStore } from "@langchain/langgraph";

const memoryStore = new MemoryStore();

记忆通过一个 tuple 来划分命名空间，在以下示例中为 (<user_id>, "memories")。命名空间可以是任意长度并表示任何内容，不必特定于用户。

const userId = "1";
const namespaceForMemory = [userId, "memories"];

使用 store.put 方法将记忆保存到存储中的命名空间。指定如上定义的命名空间，以及一个记忆的键值对：键只是记忆的唯一标识符 (memory_id)，值（一个字典）就是记忆本身。

const memoryId = crypto.randomUUID();
const memory = { food_preference: "I like pizza" };
await memoryStore.put(namespaceForMemory, memoryId, memory);

使用 store.search 方法从您的命名空间中读取记忆，该方法返回给定用户的记忆列表，最多到 limit 参数（默认 10）。使用 InMemoryStore 时，项目按插入顺序返回，因此最新的记忆在列表末尾；其他后端可能以不同方式排序记忆（参见列出命名空间中的项目）。

const memories = await memoryStore.search(namespaceForMemory);
memories[memories.length - 1];

// {
//   value: { food_preference: 'I like pizza' },
//   key: '07e0caf4-1631-47b7-b15f-65515d4c1843',
//   namespace: ['1', 'memories'],
//   createdAt: '2024-10-02T17:22:31.590602+00:00',
//   updatedAt: '2024-10-02T17:22:31.590605+00:00'
// }

它具有的属性是：

value: 此记忆的值
key: 此记忆在此命名空间中的唯一键
namespace: 字符串的元组，此记忆类型的命名空间
虽然类型是 tuple，但在转换为 JSON 时可能会序列化为列表（例如 ['1', 'memories']）。
createdAt: 此记忆创建的时间戳
updatedAt: 此记忆更新的时间戳

列出命名空间中的项目

调用 store.search 时，不带 query 和 filter 参数，将返回存储在命名空间前缀下的项目，最多返回 limit 个。当您不需要语义排序时，使用此方法来枚举命名空间中的所有内容。

// Return up to 100 items stored under ["alice", "memories"].
const items = await store.search(["alice", "memories"], { limit: 100 });

需要注意的三种行为：

namespace_prefix 通过前缀匹配，不是精确匹配。 ("alice",) 也会返回 ("alice", "memories")、("alice", "preferences") 等下的项目。要限制到单个级别，请传递完整的命名空间或在客户端根据 item.namespace 过滤返回的项目。
超过 limit 的结果将被静默截断。 没有溢出信号——将 limit 设置为高于您预期的最大值，或使用 offset 进行分页。
默认排序取决于存储后端。 PostgresStore 和 AsyncPostgresStore 返回按 updated_at 降序排列的结果（最近更新的在前）。InMemoryStore 返回按插入顺序排列的结果（最近插入的在最后）。不要依赖特定实现间的顺序；如果顺序重要，请在客户端根据 item.updated_at 进行排序。

要对大型命名空间进行分页：

const pageSize = 50;
let offset = 0;
while (true) {
  const page = await store.search(["alice", "memories"], { limit: pageSize, offset });
  if (page.length === 0) break;
  for (const item of page) {
    // ...
  }
  offset += pageSize;
}

要发现存在哪些命名空间（例如，在列出每个用户的记忆之前迭代所有用户），请使用 store.listNamespaces：

// All namespaces that start with ["alice"], truncated to two levels deep.
const namespaces = await store.listNamespaces({ prefix: ["alice"], maxDepth: 2 });

语义搜索

除了简单的检索，存储还支持语义搜索，允许您根据含义而不是精确匹配来查找记忆。要启用此功能，请使用嵌入模型配置存储：

import { OpenAIEmbeddings } from "@langchain/openai";

const store = new InMemoryStore({
  index: {
    embeddings: new OpenAIEmbeddings({ model: "text-embedding-3-small" }),
    dims: 1536,
    fields: ["food_preference", "$"], // 要嵌入的字段
  },
});

现在搜索时，您可以使用自然语言查询来查找相关的记忆：

// 查找关于食物偏好的记忆
// （这可以在将记忆放入存储后完成）
const memories = await store.search(namespaceForMemory, {
  query: "What does the user like to eat?",
  limit: 3, // 返回前 3 个匹配项
});

您可以通过配置 fields 参数或在存储记忆时指定 index 参数来控制记忆的哪些部分被嵌入：

// 存储时指定要嵌入的特定字段
await store.put(
  namespaceForMemory,
  crypto.randomUUID(),
  {
    food_preference: "I love Italian cuisine",
    context: "Discussing dinner plans",
  },
  { index: ["food_preference"] } // 仅嵌入 "food_preferences" 字段
);

// 存储时不进行嵌入（仍可检索，但不可搜索）
await store.put(
  namespaceForMemory,
  crypto.randomUUID(),
  { system_info: "Last updated: 2024-01-01" },
  { index: false }
);

在 LangGraph 中使用

memoryStore 与检查点保存器协同工作：检查点保存器将状态保存到线程（如上所述），而 memoryStore 允许您存储任意信息以便跨线程访问。如下所示，同时使用检查点保存器和 memoryStore 来编译图。

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

// 我们需要这个是因为我们想要启用线程（对话）
const checkpointer = new MemorySaver();

// ... 定义图 ...

// 使用检查点保存器和存储编译图
const graph = workflow.compile({ checkpointer, store: memoryStore });

然后像之前一样使用 thread_id 调用图，同时也使用 user_id，如前所述，它充当此特定用户的记忆的命名空间。

// 调用图
const userId = "1";
const config = { configurable: { thread_id: "1" }, context: { userId } };

// 首先，让我们向 AI 打个招呼
for await (const update of await graph.stream(
  { messages: [{ role: "user", content: "hi" }] },
  { ...config, streamMode: "updates" }
)) {
  console.log(update);
}

您可以使用 runtime 参数从任何节点访问存储和 userId。您可以使用它来保存记忆：

import { StateSchema, MessagesValue, Runtime } from "@langchain/langgraph";

const MessagesState = new StateSchema({
  messages: MessagesValue,
});

const updateMemory: GraphNode<typeof MessagesState> = async (state, runtime) => {
  // 从配置中获取用户 ID
  const userId = runtime.context?.user_id;
  if (!userId) throw new Error("User ID is required");

  // 为记忆划分命名空间
  const namespace = [userId, "memories"];

  // ... 分析对话并创建新记忆
  const memory = "Some memory content";

  // 创建新的记忆 ID
  const memoryId = crypto.randomUUID();

  // 我们创建一个新记忆
  await runtime.store?.put(namespace, memoryId, { memory });
};

您还可以从任何节点访问存储，并使用 store.search 方法获取记忆。记忆以对象列表形式返回，可以转换为字典。

memories[memories.length - 1];
// {
//   value: { food_preference: 'I like pizza' },
//   key: '07e0caf4-1631-47b7-b15f-65515d4c1843',
//   namespace: ['1', 'memories'],
//   createdAt: '2024-10-02T17:22:31.590602+00:00',
//   updatedAt: '2024-10-02T17:22:31.590605+00:00'
// }

您访问记忆并在模型调用中使用它们。

const callModel: GraphNode<typeof MessagesState> = async (state, runtime) => {
  // 从配置中获取用户 ID
  const userId = runtime.context?.user_id;

  // 为记忆划分命名空间
  const namespace = [userId, "memories"];

  // 基于最新消息进行搜索
  const memories = await runtime.store?.search(namespace, {
    query: state.messages[state.messages.length - 1].content,
    limit: 3,
  });
  const info = memories.map((d) => d.value.memory).join("\n");

  // ... 在模型调用中使用记忆
};

如果您创建一个新线程，只要 user_id 相同，您仍然可以访问相同的记忆。

// 调用图
const config = { configurable: { thread_id: "2" }, context: { userId: "1" } };

// 让我们再次打个招呼
for await (const update of await graph.stream(
  { messages: [{ role: "user", content: "hi, tell me about my memories" }] },
  { ...config, streamMode: "updates" }
)) {
  console.log(update);
}

当您在本地使用 LangSmith（例如在 Studio 中）或托管时，默认情况下可以使用基础存储，并且您无需在图编译期间指定它。但是，要启用语义搜索，您确实需要在 langgraph.json 文件中配置索引设置。例如：

{
    ...
    "store": {
        "index": {
            "embed": "openai:text-embeddings-3-small",
            "dims": 1536,
            "fields": ["$"]
        }
    }
}

有关更多详细信息和配置选项，请参阅部署指南。

后续步骤

向 Agent Server 添加自定义存储 — 部署您的实现
检查点保存器 — 线程范围的状态持久化

Connect these docs to Claude, VSCode, and more via MCP for real-time answers.

Edit this page on GitHub or file an issue.

Get started

Capabilities

Production

Frontend

LangGraph APIs

存储

基本用法

列出命名空间中的项目

语义搜索

在 LangGraph 中使用

后续步骤

​基本用法

​列出命名空间中的项目

​语义搜索

​在 LangGraph 中使用

​后续步骤

基本用法

列出命名空间中的项目

语义搜索

在 LangGraph 中使用

后续步骤