1. 短期记忆到底是什么？

Short-term Memory = 当前 thread 内的状态保存。它让 Agent 在同一段会话里记住前面发生过什么。

LangChain 官方把短期记忆叫做 thread-level persistence。意思很直接：同一个 thread 里的多轮交互，会被组织成一条会话线。Agent 每次执行时，先读这个 thread 的状态，再把新结果写回去。

它不是长期用户画像。它也不是向量库。它更像一次工单、一次客服咨询、一次下单流程里的“当前上下文”。

会话主键：thread_id。

状态容器：AgentState。

消息字段：messages。

保存器：checkpointer。

生产落地：数据库型 checkpointer。

2. 为什么不能只靠历史消息硬塞？

很多新手会把历史消息放在一个 Python list 里。Demo 可以。生产不行。

服务一重启，变量就没了。

多实例部署，上一轮请求和下一轮请求可能不在同一台机器。

多用户并发，变量管理不好就会串上下文。

长对话全塞给模型，成本高、速度慢、效果还会变差。

短期记忆的目标不是“记住越多越好”，而是“同一段会话里，该记的状态不能丢”。

3. 一张图看懂运行主线

每次调用 Agent，流程都差不多：拿到 thread_id，读取 checkpoint，合并新消息，执行模型和工具，再保存新的 checkpoint。

这就是它比普通聊天历史更工程化的地方：状态不是临时变量，而是图运行的一部分。

4. 四个核心对象

不要被 Memory 这个词吓到。源码里没有魔法。就是状态、主键、保存器、消息合并。

记住这句话：thread_id 定位会话，checkpointer 保存快照，AgentState 装状态，add_messages 合并消息。

5. 最短代码：让 Agent 记住同一段会话

from langchain.agents import create_agent
from langgraph.checkpoint.memory import InMemorySaver
agent = create_agent(
 model="openai:gpt-4o-mini",
 tools=[],
 checkpointer=InMemorySaver(),
)
config = {"configurable": {"thread_id": "tenant1:user1001:chat001"}}
agent.invoke(
 {"messages": [{"role": "user", "content": "我叫张三"}]},
 config=config,
)
agent.invoke(
 {"messages": [{"role": "user", "content": "我叫什么？"}]},
 config=config,
)

关键不是代码长短。关键是两个参数：创建 Agent 时传 checkpointer；调用 Agent 时传 thread_id。

同一个 thread_id，Agent 会恢复同一段会话的状态。换一个 thread_id，就是一段新会话。

6. 源码主线：一条线看穿

源码最值得看的是这条链路。模型只是其中一个节点。真正保存上下文的是 LangGraph 的 state 和 checkpointer。

注意：checkpointer 保存的是图状态快照，不是“最终回答文本”。messages 只是状态中的一个 channel。

7. AgentState 源码：默认状态就是 messages

LangChain 新版 Agent 默认状态里有一个核心字段：messages。它是对话历史，也是工具调用结果的载体。

class AgentState(TypedDict):
 messages: Required[Annotated[list[AnyMessage], add_messages]]
 jump_to: NotRequired[...]
 structured_response: NotRequired[...]

这段源码透露了两个关键信号。

messages 是 Required：Agent 必须围绕消息运行。

messages 绑定 add_messages：新消息不是简单覆盖，而是通过 reducer 合并。

所以短期记忆不是你手动拼接字符串。它是图状态的字段，由 reducer 控制更新方式。

8. Checkpointer 源码：thread_id 是查找入口

InMemorySaver 是最容易读懂的实现。它用内存字典保存 checkpoint。生产环境可以换成 PostgresSaver 等数据库实现。

# InMemorySaver 的核心结构可以简化理解为：
storage[thread_id][checkpoint_ns][checkpoint_id] = checkpoint
writes[(thread_id, checkpoint_ns, checkpoint_id)] = task_writes
blobs[(thread_id, checkpoint_ns, channel, version)] = serialized_value

源码里的 get_tuple(config) 会按 thread_id 找 checkpoint。put(...) 会把新的 checkpoint 写回。delete_thread(thread_id) 可以删除整条会话。

InMemorySaver 适合本地测试。线上不要用它保存真实会话状态。

9. thread_id：短期记忆的主键

thread_id 不是随便起的。它决定了状态隔离边界。

同一个 thread_id：继续同一段会话。

不同 thread_id：互相隔离。

不要只用 user_id：一个用户可能同时打开多个会话。

推荐格式：tenantId:userId:sessionId。

这也是多租户系统必须注意的地方。thread_id 设计不好，轻则上下文混乱，重则数据串租户。

10. 当前会话不只保存聊天记录

企业业务里，当前会话状态往往不只是 messages。比如客服系统还要记住订单号、问题类型、处理阶段。

from langchain.agents import AgentState
class CustomAgentState(AgentState):
 user_id: str
 order_id: str | None
 step: str | None

工具和中间件可以读取这些状态。比如工具通过 runtime.state 获取当前会话数据；中间件通过 request.state 在模型调用前改写上下文。

短期状态适合保存“当前流程”。长期偏好和画像，应该进入 Long-term Memory / Store。

11. 长对话要管，不要无限塞

短期记忆会让 messages 越来越长。长到一定程度，模型会慢、会贵、会跑偏。

官方常见处理模式有三类：裁剪消息、删除消息、摘要消息。生产里通常三种都会用。

最近几轮：保留原文。

很早之前：压缩成摘要。

无关内容：直接删除。

敏感内容：脱敏后再存，或根本不存。

12. 生产环境怎么做？

本地可以用 InMemorySaver。生产建议用数据库型 checkpointer。Postgres 是常见选择。

from langchain.agents import create_agent
from langgraph.checkpoint.postgres import PostgresSaver
DB_URI = "postgresql://user:password@host:5432/db?sslmode=disable"
with PostgresSaver.from_conn_string(DB_URI) as checkpointer:
 checkpointer.setup() # 第一次使用时创建表
 agent = create_agent(
 model="openai:gpt-4o-mini",
 tools=[],
 checkpointer=checkpointer,
 )

重点不是换一个类名。重点是把会话状态从进程内存，搬到可靠存储。

13. 上线前检查清单

Memory 是能力，也是风险。状态一旦保存，就要考虑隔离、清理、审计、恢复和隐私。

Agent 会“记住”什么，不应该只由模型决定，必须由工程系统决定。

14. 总结

短期记忆的本质很简单：在同一个 thread 里，把 Agent 的状态保存下来。下一轮调用时，再把状态拿回来继续。

这一章只讲当前会话。下一章讲 Long-term Memory：如何跨会话记住用户偏好、事实和画像。