企业官网建设流程全解析

Agent 应用落地时，最常卡住的往往不是模型选型，而是记忆。对话转两圈就忘了前面说过什么，任务执行到一半主题就偏了，重启服务后所有上下文清零，多 Agent 协作时大家各记各的，信息根本对不上。这次我们就把 Agent 记忆这件事完整拆开：先讲清楚失忆的原因，再给出一套可以直接落地的记忆方案，覆盖短时记忆、长期记忆、向量检索、多 Agent 共享记忆和持久化。

这套教程最值得关注的点有三个：一是把记忆问题分层拆解，不再笼统地说“加一个历史记录”；二是所有方案都给出可运行的 Python 示例，方便在本地环境直接验证；三是重点考虑了工程落地，包括重启恢复、批量写入、接口封装和资源占用。内容上不绑定某一个商业平台，你可以用 OpenAI 的接口、Ollama 本地模型，也可以接入任何兼容 OpenAI 协议的服务。

如果你正在做客服助手、知识库问答、自动化办公 Agent、多角色协作系统，或者想在现有 RAG 应用里加入“长期记住用户偏好”的能力，这篇文章可以收藏备用。我们先从最核心的问题开始：Agent 为什么会失忆。

1. Agent 记忆核心能力速览

任何记忆方案都由四个部分组成：消息存储、上下文组装、检索召回、状态恢复。后面的实操章节会围绕这四个部分展开。这里先明确一点：没有一种万能记忆方案，必须根据你的实际场景决定记忆粒度、存储介质和过期策略。

2. Agent 为什么会“失忆”

2.1 大模型的上下文窗口导致“装不下”

大模型不是记不住，而是每次推理都要在固定长度的上下文窗口内工作。当前对话历史越长，能够使用的剩余空间就越少。当历史对话超过窗口长度，系统只保留最后 N 条消息，最早的用户需求、关键约束、中间确认过的细节都会被迫丢弃。用户感知到的是“Agent 把我最开始说的话忘了”，本质上就是上下文被截断。

即便新一代模型把上下文窗口做到很大，直接堆历史也不是长久之计。每轮对话都把所有历史发给模型，会带来两个问题：一是按 token 计的推理成本持续上涨，二是输入变长后首字延迟明显增加。实际项目中通常会限制送入模型的最近消息数量，这时候就必须有更精细的记忆管理，而不是简单粗暴地全部保留。

2.2 会话无状态，重启即失忆

大部分 Agent 进程默认是“无状态”的。启动时从空列表开始，任务结束后内存里的对话记录全部释放，服务一重启，历史就归零。这跟人的记忆机制不一样：人可以被动地回忆起昨天讨论过什么，而 Agent 如果没有外部存储，就完全没有过去。

要让 Agent 具备持久记忆，必须把状态外置到数据库、文件或缓存中。会话 ID、用户 ID、Agent ID 都需要作为记忆的索引字段。否则，即使你做了存储，重启后也无法把正确的历史重新加载回上下文。

2.3 多 Agent 信息孤岛

在多智能体系统中，失忆问题更明显。每个 Agent 都维护自己的上下文，主 Agent 把任务分发给子 Agent 后，子 Agent 的执行过程、读取到的材料、完成的中间结果如果没有回流到一个统一记忆层，就会出现信息孤岛。最典型的表现是：客服 Agent 已经在前面确认了用户所在城市，后面推荐 Agent 还要再问一遍。

解决多 Agent 失忆，不只是把每段对话记下来，而是要让多个 Agent 共享同一个记忆读写接口。这里涉及分区、权限、读写一致性和冲突处理，在后面的实战部分会专门讲。

2.4 检索不到位，记住也白记

还有一种情况是：信息已经存入向量库，但 Agent 仍然表现得像失忆。原因通常是检索环节出了问题。查询改写不准确、top_k 设置太小、embedding 模型与本场景不匹配、向量库里的元数据过滤条件错误，都会导致召回不到真正有用的内容。

所以，记忆方案并不等于存储方案。存储只解决“信息还在”的问题，检索才决定“信息能不能被想起来”。从工程角度看，检索质量和写入质量同样重要。

3. Agent 记忆的三种层次

3.1 短时记忆：对话上下文直接拼接

短时记忆就是把最近几轮对话作为提示词拼接进模型输入。它最简单，也很有效，适合大多数对话型 Agent。实现方式包括内存列表、Redis 列表、数据库消息表等。关键参数是窗口大小：窗口太大，token 成本高；窗口太小，容易丢失早期信息。实际项目中可以按轮数限制，也可以按 token 数限制。

短时记忆最大的问题是无法跨会话持久。用户第二天再来问同样的问题，Agent 不会记得之前聊过什么。所以它通常作为记忆体系的第一层，而不是全部。

3.2 工作记忆：当前任务的状态空间

工作记忆更接近“任务执行到哪一步”的状态管理，常用在自动化 Agent 和工具调用型 Agent 中。比如一个写文档的 Agent，当前文档路径、已选模板、正在编辑章节的编号、用户最新一次修改意见，这些都属于工作记忆。

在 LangGraph 这类编排框架中，工作记忆通常用 State 对象表达。State 会在图的节点之间传递，并在执行结束后选择是否写入持久化存储。工作记忆的设计要点是：只放“当前任务必须保留”的信息，任务结束或失败后要有清理机制，避免残留状态污染下一次任务。

3.3 长期记忆：向量库加结构化存储

长期记忆要解决的是跨会话的信息沉淀问题：用户偏好、历史结论、项目背景、常见限制条件。它不能简单地把所有对话原样堆进提示词，而是需要在对话过程中抽取关键信息，再在需要时检索召回。

技术实现上，长期记忆通常分成两条线。一是非结构化记忆，用向量数据库保存关键事实和事件描述，检索时按语义相似度召回；二是结构化记忆，用 SQLite、PostgreSQL 或 Redis 保存用户属性、任务状态、标签等字段化信息，按精确条件查询。两条线互补：结构化存储适合“用户住在哪里”“工单编号是什么”这类确定性问题，向量存储适合“之前有没有讨论过类似方案”这类模糊问题。

这里也解释一个容易混淆的概念：LSTM 中的记忆是把信息编码到网络参数内部，用门控机制控制写入和遗忘；而 Agent 场景下的记忆是外部化记忆，把信息放到数据库或文件中，由 Agent 按需读取。两者解决的问题不同：LSTM 适合序列建模，Agent 外部记忆适合复杂任务状态管理。学习 Agent 记忆时，不必拘泥于 LSTM 的内部记忆思路，重点应该放在存储、索引、检索、更新这一套外部流程上。

3.4 三种记忆怎么配合

实际 Agent 系统往往三层同时存在。短时记忆负责当前会话流畅度，工作记忆负责任务执行不跑偏，长期记忆负责跨时间的用户和领域知识沉淀。三层之间还需要同步：例如用户在一次长对话中说了一个重要偏好，这个偏好要从短时记忆中抽取出来，写入长期记忆，下次会话才能直接命中。

4. 主流 Agent 记忆框架选型

4.1 LangChain Memory 模块

LangChain 提供了较完整的对话记忆组件，包括 ConversationBufferMemory、ConversationSummaryMemory、ConversationBufferWindowMemory、VectorStoreRetrieverMemory 等。早期版本用起来简单，直接塞进 Chain 即可，适合快速验证。但当你需要精细控制消息格式、跨线程隔离或自定义持久化时，LangChain 的 Memory 组件会显得有些重，而且不同版本 API 变动较大，写代码时要注意锁定版本。

4.2 LangGraph State 与 LangMem

LangGraph 是比 LangChain 更接近工程落地的编排框架，它把工作记忆建立在 State 机制上。State 是节点间传递的数据结构，可以定义消息列表、自定义字段、临时标记等。LangGraph 还支持 checkpoint，能够把某个时间点的全部状态持久化，恢复后可以继续执行。LangMem 则是专门用于长期记忆和记忆管理的组件，支持从对话中提取记忆、存储记忆、更新记忆，并允许 Agent 在需要时主动读写记忆。

4.3 Mem0

Mem0 是一个独立的记忆管理框架，主打“给 Agent 一个长期记忆层”。它可以把用户的偏好、习惯、决策结果以记忆条目的形式存储，并提供增删改查和语义检索接口。Mem0 的特点是把记忆操作设计得比较完整，适合那些不想自己折腾向量库和消息表的团队。本地跑或者调用托管服务都可以，具体部署方式要看官方文档。

4.4 LlamaIndex Memory

LlamaIndex 主要面向 RAG 场景，它的 Memory 模块更关注“如何在检索增强生成中组织历史与文档片段”。如果你的核心需求是把已有文档和过往问答记录结合起来让 Agent 使用，LlamaIndex 的 ChatMemoryBuffer、VectorMemory 等组件可以参考。它和 LangChain 属于不同生态，选型时要看你的主框架。

4.5 自研方案

框架只是工具。很多生产级 Agent 项目最终会选择自研一套轻量记忆服务，把核心逻辑控制在几个接口上：写入记忆、读取记忆、搜索记忆、删除记忆。自研的好处是数据结构完全可控，坏处是要自己处理向量检索、持久化、并发和清理策略。

更稳妥的做法是：先用现成框架做原型验证，确认记忆条目的结构、检索规则和更新策略后，再根据业务场景抽象成独立的记忆服务。下面几章的示例代码会按这个思路走，所以即使你不选某一个框架，也能直接迁移到自己的项目里。

5. 本地部署环境准备

5.1 基础运行环境

Agent 记忆方案通常用 Python 开发。建议准备一个独立的虚拟环境，避免和系统全局包冲突。基础检查清单如下：

• 操作系统：Windows / Linux / macOS 均可
• Python 版本：3.10 或更高
• 包管理工具：pip、uv 或 poetry
• 代码管理：Git
• 本地模型服务：可选 Ollama、vLLM，或直接使用云端 API

初始化虚拟环境：

python -m venv .venv source .venv/bin/activate # Windows 下执行 .venv\Scripts\activate

5.2 LLM 接入方式

记忆系统要能正常工作，需要大模型参与“抽取关键记忆”和“根据记忆生成回答”两个环节。接入方式有三种：云端模型 API、本地模型服务、企业内部网关。例如用 OpenAI 兼容 API：

export OPENAI_API_KEY="your_api_key" export OPENAI_BASE_URL="http://127.0.0.1:8080/v1" # 如果使用本地网关

在本地没有 GPU 的情况下，也可以先用 Ollama 跑 7B 到 14B 级别的模型完成原型测试，重点验证记忆抽取和检索逻辑，而不是模型回答质量。

5.3 向量数据库选型

长期记忆依赖向量检索。常用方案中，Chroma 最轻量，适合单机测试；FAISS 适合大规模向量索引；Qdrant 和 pgvector 更适合生产部署，支持过滤、持久化和网络访问。首次验证阶段建议直接使用 Chroma，它会自动把向量数据落盘，省去单独启动数据库服务的步骤。

5.4 硬件门槛与资源预估

从通用经验看，单纯做记忆服务和向量检索对显存要求不高，CPU 上也能跑。主要开销来自 Embedding 模型和 LLM 推理。Embedding 模型可以选择 300MB 以内的小模型，在 CPU 上也能接受；LLM 如果使用本地 7B 模型，则需要考虑 8GB 以上内存或 6GB 以上显存。实际占用要以你选择的模型和推理参数为准，不要在项目前期假设特定数字。

6. 短时记忆实战：最小可运行示例

6.1 安装依赖

这里的示例不绑定复杂框架，先用 Python 标准库实现一个可持久化的短时记忆，底清楚后再替换成向量库。

pip install fastapi uvicorn pydantic

6.2 实现 JSON 消息存储

以下代码实现了一个最简单的消息存储：按用户和会话追加消息，重启后可以从本地 JSON 文件恢复。

import json import os from datetime import datetime MEMORY_FILE = "./memory_store.json" def load_memory(): if os.path.exists(MEMORY_FILE): with open(MEMORY_FILE, "r", encoding="utf-8") as f: return json.load(f) return [] def save_memory(memory): with open(MEMORY_FILE, "w", encoding="utf-8") as f: json.dump(memory, f, ensure_ascii=False, indent=2) def add_message(user_id, session_id, role, content): memory = load_memory() memory.append({ "user_id": user_id, "session_id": session_id, "role": role, "content": content, "time": datetime.now().isoformat() }) save_memory(memory) def get_recent_messages(user_id, session_id, limit=10): memory = load_memory() messages = [m for m in memory if m["user_id"] == user_id and m["session_id"] == session_id] return messages[-limit:]

这个例子很简单，但已经具备短时记忆的核心：追加、读取、按会话隔离、持久化。你可以把 JSON 文件替换成 SQLite 或 Redis，逻辑不变。

6.3 带 LLM 的多轮对话验证

模拟一个客服 Agent：

from openai import OpenAI client = OpenAI() def chat(user_id: str, session_id: str, user_input: str) -> str: history = get_recent_messages(user_id, session_id, limit=10) messages = [{"role": "system", "content": "你是客服助手，请结合历史对话回答。"}] for msg in history: messages.append({"role": msg["role"], "content": msg["content"]}) messages.append({"role": "user", "content": user_input}) resp = client.chat.completions.create( model="gpt-4o-mini", # 可替换为本地模型网关中的模型名 messages=messages, temperature=0.3 ) answer = resp.choices[0].message.content add_message(user_id, session_id, "user", user_input) add_message(user_id, session_id, "assistant", answer) return answer if __name__ == "__main__": print(chat("u_1001", "s_1", "我叫张三，我在做一个 Agent 记忆项目。")) print(chat("u_1001", "s_1", "我叫什么名字？在做什么项目？"))

6.4 测试步骤与预期结果

测试目的是验证短时记忆是否能让 Agent 在第二轮对话中记住第一轮提到的“张三”和“Agent 记忆项目”。操作步骤是先运行脚本，观察第二次问答是否正确输出姓名和项目名称。如果 Agent 给出了正确答案，说明短时记忆链路已经跑通。

接着重启进程，再次发起相同的第二轮问题。因为这里用的是 JSON 文件持久化，正常也能回答上来。如果换用纯内存列表，重启后就会失忆，这也是持久化与不持久化最直观的区别。

常见失败原因如下：

7. 长期记忆实战：向量库写入与检索

7.1 为什么需要向量库

短时记忆解决“这几轮说过什么”，长期记忆要解决“之前是否提过某个重要信息”。当历史积累到几百条甚至上千条，把所有记录拼进提示词既浪费 token，检索效率也低。正确做法是用 Embedding 模型把记忆文本向量化，再按用户和会话的元数据过滤，只召回与当前问题相关的少量记忆片段。

7.2 Chroma 持久化示例

安装依赖：

pip install chromadb langchain-chroma langchain-openai

这里的代码使用 OpenAI Embedding 接口作为示例。如果你使用本地模型，可以把 Embedding 类替换成 OllamaEmbeddings 或其他兼容实现。

from langchain_chroma import Chroma from langchain_openai import OpenAIEmbeddings # 初始化向量库，自动落盘到 ./chroma_memory vectorstore = Chroma( collection_name="agent_long_term_memory", embedding_function=OpenAIEmbeddings(model="text-embedding-3-small"), persist_directory="./chroma_memory" ) # 写入长期记忆 memories = [ "用户偏好使用 Python，项目名称是 AgentMemory。", "用户当前在深圳，希望推荐线下交流活动。", "用户之前表示对成本比较敏感，不建议使用高价的云 API。" ] vectorstore.add_texts( texts=memories, metadatas=[ {"user_id": "u_1001", "source": "conversation", "time": "2026-01-01"}, {"user_id": "u_1001", "source": "conversation", "time": "2026-01-02"}, {"user_id": "u_1001", "source": "conversation", "time": "2026-01-03"} ] )

7.3 按查询召回记忆

query = "用户喜欢用什么语言开发项目？" docs = vectorstore.similarity_search_with_score( query, k=3, filter={"user_id": "u_1001"} ) for doc, score in docs: print(f"score: {score:.4f}") print(doc.page_content)

预期结果是召回第一条“用户偏好使用 Python”，且该条得分明显高于其他不相关内容。这里需要理解的是，得分是一个相对值，不同 Embedding 模型的分数分布差异很大，不建议跨模型对比绝对分数。

7.4 记忆写入与检索的完整链路验证

一个完整的长期记忆链路应当包括四个步骤：

1. 注入阶段：LLM 多轮对话后，把最新消息送入记忆抽取模型，提取可以长期保存的事实。
2. 写入阶段：把抽取结果写入向量库和结构化存储，并附带 user_id、session_id、topic 等元数据。
3. 检索阶段：用户提出新问题时，先用查询关键词或 LLM 改写得到检索文本，再执行向量检索。
4. 组装阶段：把检索到的记忆片段拼入 system prompt 或上下文，让模型在回答时参考。

判断这套流程是否成功，可以设计三个测试用例：

如果第二个用例失败了，先检查持久化目录是否存在、元数据过滤条件是否写对、查询向量是否由相同的 Embedding 模型生成。第三个用例失败时，需要调整检索阈值或增加“回答不了就明确说不知道”的指令。

8. 多 Agent 共享记忆与 API 封装

8.1 为什么需要共享记忆

多 Agent 协同场景中，一个用户问题可能会经过路由 Agent、检索 Agent、生成 Agent、审核 Agent。如果每个 Agent 只读自己的本地上下文，就会出现“路由 Agent 已经判断出用户需要退款，生成 Agent 却不知道退款条件”的割裂情况。共享记忆要解决的核心问题就是：把关键状态放到所有 Agent 都能读到的位置。

8.2 按 Agent 与用户分区的数据库设计

共享记忆不是让所有 Agent 读同一个列表，而是要按维度分区。推荐的数据模型至少包含以下字段：

使用 SQLite 的 JSON 存储也可以，但最好把 agent_id 和 user_id 都作为过滤条件。这样既能做到跨 Agent 共享该用户的信息，又能避免不同用户之间串数据。

8.3 FastAPI 封装记忆读写接口

下面的代码演示如何用 FastAPI 暴露一个通用的记忆检索接口。

from fastapi import FastAPI from pydantic import BaseModel from typing import Optional app = FastAPI() class MemoryQuery(BaseModel): agent_id: str user_id: str query: str top_k: int = 5 memory_type: Optional[str] = None class MemoryWriteRequest(BaseModel): agent_id: str user_id: str session_id: str content: str memory_type: str = "general" @app.post("/memory/search") async def search_memory(req: MemoryQuery): # 这里替换为实际的向量库检索逻辑 # 示例返回值，实际应根据存储结果返回 return { "agent_id": req.agent_id, "user_id": req.user_id, "results": [] } @app.post("/memory/write") async def write_memory(req: MemoryWriteRequest): # 这里写入向量库和结构化存储 return {"status": "ok", "memory_id": "m_10001"}

启动服务：

uvicorn memory_service:app --host 0.0.0.0 --port 8000

需要说明的是，这只是一个接口骨架，实际写入和检索逻辑要替换成你自己的向量库调用。封装成 API 后，任何语言编写的 Agent 都可以通过 HTTP 访问记忆层，不需要都依赖 Python 框架。

8.4 批量任务与导入导出

真实项目中经常需要批量写入历史对话，比如把之前的客服聊天记录导入为长期记忆。批量任务的设计要点是：

• 分批写入，避免一次性加载全部数据导致内存溢出。
• 写入完成后校验条数，和源数据比对。
• 遇到网络异常或向量库写入失败时，记录失败索引，稍后重试。
• 导入前去除敏感字段，例如身份证号、银行卡号、明文密码。

批量导出逻辑类似，一般按 user_id 或时间范围导出 JSONL 文件，方便迁移和分析。

9. 资源占用与性能观察

9.1 重点观察指标

如果本地使用 Ollama 或其他本地 LLM，显存占用取决于模型大小和并发数。不要只看静态显存，还要观察多路并发时的峰值。向量库的检索延迟通常受数据总量、索引类型、top_k 和过滤条件影响，数据量大时要考虑为高频率查询的 agent_id、user_id 建立索引。

9.2 降低开销的思路

• 使用更轻量的 Embedding 模型，比如几十 MB 到几百 MB 的模型。
• 长期记忆按用户分库或分 collection，减少全局扫描量。
• 短时记忆只保留最近 N 条，防止无限增长。
• 批量写入时合并向量库的写入事务，减少频繁落盘。
• 为高频查询加 Redis 缓存，热点用户偏好可以走缓存而不走向量检索。

10. 常见问题与排查方法

加载向量库时如果遇到MaxRetryError，多半是本地的 embedding 服务地址没有启动，或者网络被网关策略拦截。先在命令行测试 embedding 接口连通性，再排查向量库代码。

11. 最佳实践与使用建议

记忆设计不能等 Agent 写完了再补。从第一个原型阶段就要确定三个问题：记忆存哪里、谁可以读、什么时候清理。缺少清理策略的记忆库会越积越乱，旧记忆和新记忆冲突时，Agent 会表现出“明明数据库有正确信息，却回答错”的怪异行为。

合规方面，涉及真实用户对话记录的记忆系统必须注意隐私和授权。对话内容如果包含个人信息、医疗信息、财务信息，应该做脱敏处理，至少需要获得用户授权。人脸、声音、肖像类信息在 Agent 记忆中的使用边界更严格，生成和调用前必须确认授权范围，不能拿未授权的数据去做二次加工。涉及版权素材的场景，比如从文档中抽取长期记忆，也要确保文档来源合法。

工程上建议给每条记忆增加置信度和来源字段，来源可以是“用户主动声明”“模型推断”“系统日志”。模型推断出来的记忆在生成回答时不能当成硬约束，应该等用户确认后再升级为事实。这是避免 Agent 一本正经地利用错误记忆的核心手段。

批量任务的稳定性比单条读写更关键。在接入生产环境前，至少要做一次万条级别的历史对话导入测试，检查是否存在内存溢出、重复写入、字段截断等问题。批量任务要加变更日志，方便回滚。

接口服务要限制访问范围。如果记忆 API 暴露在公网，需要加 token 认证或内网访问控制，否则任何能访问接口的人都能读取用户历史，这是较严重的数据泄露风险。

12. 总结与下一步

这套 Agent 记忆方案最值得尝试的地方，是它的可迁移性。从 JSON 文件级的短时记忆，到 Chroma 向量库的长期记忆，再到 FastAPI 封装的多 Agent 共享记忆，每个环节都能单独验证，也能组合起来形成完整链路。最先应该验证的是“重启后跨会话记忆”这个功能，它直接决定记忆方案是否具有生产价值。

最容易踩的坑有两个：一是向量检索的过滤条件写错，导致不同用户之间数据串线；二是记忆更新策略缺失，旧记忆一直占据检索结果，新记忆反而召不回。把这两个点提前解决，剩下的主要工作就是调优检索质量和响应耗时。

后续可以继续扩展的方向包括：多模态记忆，让 Agent 记住图片和语音中的关键信息；关系型记忆，用图数据库表达用户、项目、事件之间的关联；个性化记忆增强，把记忆和推荐系统结合起来，让 Agent 根据历史偏好主动提供建议。记忆不是一次建模就能完成的工程，它需要和业务一起持续迭代。建议把这篇文章里的最小示例保留为项目模板，后续每次新增功能都在上面做回归测试。