27-langchain-long-term-memory.md

27. 长期记忆（Long-term memory）

原文链接: https://docs.langchain.com/oss/python/langchain/long-term-memory

概述（Overview）

LangChain 智能体通过 LangGraph 的持久化能力来实现长期记忆。这是一个相对高级的主题，需要对 LangGraph 有一定了解。

---

记忆存储（Memory storage）

LangGraph 使用一个 store 将长期记忆以 JSON 文档形式持久化：

• 每条记忆存放在一个自定义的 namespace（类似“文件夹”）下；
• 在该命名空间下用一个唯一的 key（类似“文件名”）标识；
• 命名空间通常会包含用户 ID、组织 ID 或其他标签，便于按层级组织信息；
• 支持跨命名空间的内容过滤与相似度搜索。

from langgraph.store.memory import InMemoryStore


def embed(texts: list[str]) -> list[list[float]]:
    # 这里应替换为真实的 embedding 函数或 LangChain 的 embeddings 对象
    return [[1.0, 2.0] * len(texts)]


# InMemoryStore 将数据保存在内存字典中，生产环境应使用 DB 驱动的 store
store = InMemoryStore(index={"embed": embed, "dims": 2})
user_id = "my-user"
application_context = "chitchat"
namespace = (user_id, application_context)

store.put(
    namespace,
    "a-memory",  # key
    {
        "rules": [
            "User likes short, direct language",
            "User only speaks English & python",
        ],
        "my-key": "my-value",
    },
)

# 通过 ID 读取这条“记忆”
item = store.get(namespace, "a-memory")

# 在该命名空间内搜索“记忆”：
# 按内容过滤（filter）并按向量相似度排序
items = store.search(
    namespace, filter={"my-key": "my-value"}, query="language preferences"
)

关于 memory store 的更多信息可参见 Persistence 指南。

---

在工具中读取长期记忆（Read long-term memory in tools）

下面示例展示一个“查询用户信息”的工具，供智能体调用：

from dataclasses import dataclass

from langchain_core.runnables import RunnableConfig
from langchain.agents import create_agent
from langchain.tools import tool, ToolRuntime
from langgraph.store.memory import InMemoryStore


@dataclass
class Context:
    user_id: str


# InMemoryStore 将数据保存在内存字典中，生产环境应使用 DB 驱动的 store
store = InMemoryStore()

# 使用 put 方法向 store 写入一些示例数据
store.put(
    ("users",),           # 命名空间，用于归类相关数据（这里是用户数据）
    "user_123",          # 命名空间内的 key（这里用 user ID 作为 key）
    {
        "name": "John Smith",
        "language": "English",
    },                     # 为该用户存储的数据
)


@tool
def get_user_info(runtime: ToolRuntime[Context]) -> str:
    """Look up user info."""
    # 访问与 create_agent 传入的同一个 store
    store = runtime.store
    user_id = runtime.context.user_id
    # 从 store 获取数据，返回的是带有 value 与 metadata 的 StoreValue 对象
    user_info = store.get(("users",), user_id)
    return str(user_info.value) if user_info else "Unknown user"


agent = create_agent(
    model="claude-sonnet-4-5-20250929",
    tools=[get_user_info],
    # 将 store 传给智能体，使其在运行工具时可访问该 store
    store=store,
    context_schema=Context,
)

# 运行智能体
agent.invoke(
    {"messages": [{"role": "user", "content": "look up user information"}]},
    context=Context(user_id="user_123"),
)

---

在工具中写入长期记忆（Write long-term memory from tools）

下面示例展示一个“更新用户信息”的工具：

from dataclasses import dataclass
from typing_extensions import TypedDict

from langchain.agents import create_agent
from langchain.tools import tool, ToolRuntime
from langgraph.store.memory import InMemoryStore


# InMemoryStore 将数据保存在内存字典中，生产环境应使用 DB 驱动的 store
store = InMemoryStore()


@dataclass
class Context:
    user_id: str


# TypedDict 定义了用户信息的结构，方便 LLM 理解与校验
class UserInfo(TypedDict):
    name: str


# 允许智能体更新用户信息的工具（常用于聊天应用）
@tool
def save_user_info(user_info: UserInfo, runtime: ToolRuntime[Context]) -> str:
    """Save user info."""
    # 访问与 create_agent 传入的同一个 store
    store = runtime.store
    user_id = runtime.context.user_id
    # 将数据写入 store（命名空间、key、data）
    store.put(("users",), user_id, user_info)
    return "Successfully saved user info."


agent = create_agent(
    model="claude-sonnet-4-5-20250929",
    tools=[save_user_info],
    store=store,
    context_schema=Context,
)

# 运行智能体
agent.invoke(
    {"messages": [{"role": "user", "content": "My name is John Smith"}]},
    # 通过 context 中的 user_id 指明要更新哪位用户的信息
    context=Context(user_id="user_123"),
)

# 你也可以直接从 store 读取刚刚写入的数据
store.get(("users",), "user_123").value

---

本文档由 LangChain 官方文档翻译而来