企业官网建设流程全解析

1. 从状态管理到记忆系统：前端思维的一次关键跃迁

做前端转型 Agent 开发的朋友，聊到第六篇，基本都会撞上同一堵墙：前面几篇把工具调用、任务编排、提示词链路都跑通了，Demo 看着挺唬人，可一旦连续对话超过五轮，Agent 就开始“失忆”——上一句刚说过的偏好，下一句就忘得干干净净。这不是模型不行，而是我们压根没给它装记忆。

我刚开始做 Agent 的时候，脑子里全是 React 那套状态管理：useState、useReducer、全局 store，数据流清晰可控。但 Agent 的“状态”跟 UI 状态完全是两码事。UI 状态是确定性的、可枚举的、生命周期跟着组件走；而 Agent 的记忆是模糊的、海量的、需要检索和衰减的。你不可能把所有历史对话塞进一个数组然后map出来渲染，因为上下文窗口就那么大，token 是要花钱的。

这一篇就专门聊 Agent Memory 记忆系统。我会从前端开发者最容易理解的视角切入，把记忆系统拆成几个可落地的模块：短期记忆怎么管、长期记忆怎么存、检索怎么做、遗忘机制怎么设计。每个部分都会给出具体的实现思路和踩坑经验，代码用 TypeScript 和 Python 混合示意，因为实际项目里往往是前端调 API、后端跑逻辑。看完你应该能给自己手上的 Agent 加上一套真正能用、不花冤枉钱的记忆系统。

提示：记忆系统不是“把聊天记录存数据库”这么简单。它涉及存储结构、检索策略、上下文组装、成本控制四个层面的协同设计，缺一个都会导致 Agent 表现不稳定。

2. 短期记忆与长期记忆的分层设计逻辑

2.1 为什么不能把所有对话都塞进上下文

先算一笔账。假设一轮对话平均 200 个 token，用户跟 Agent 聊了 50 轮，那就是 10000 个 token。听起来还好？但实际场景里，Agent 每轮回复可能带工具调用结果、代码片段、文档摘要，单轮轻松突破 2000 token。50 轮下来就是 10 万 token。主流模型的上下文窗口虽然标称 128K，但真正有效利用的往往只有前 30% 到 50%，越往后模型对中间内容的注意力越弱，这就是所谓的“迷失在中间”现象。

更现实的问题是成本。按输入 token 计费的话，每轮都把 10 万 token 的历史全量传进去，一次调用就是几毛到几块钱。用户聊 100 轮，你的账单能吓死人。所以短期记忆和长期记忆必须分开设计：短期记忆负责“当前任务上下文”，长期记忆负责“跨会话的用户画像和知识沉淀”。

前端开发者可以这样类比：短期记忆像是组件内的useState，生命周期短、跟当前渲染强相关；长期记忆像是持久化到 localStorage 或后端数据库的用户偏好，跨会话存在、需要时再取。区别在于，Agent 的“取”不是简单读取，而是语义检索。

2.2 短期记忆的滑动窗口与摘要压缩

短期记忆的核心目标是：在有限的 token 预算内，保留对当前任务最有价值的信息。我试过几种方案，最后稳定下来的是“滑动窗口 + 阶段性摘要”的组合。

滑动窗口很好理解：只保留最近 N 轮对话原文。N 取多少？我的经验是 6 到 10 轮，具体看单轮长度。如果单轮平均 500 token，那 8 轮就是 4000 token，加上系统提示词和工具定义，控制在 6000 以内比较安全。超过窗口的老对话不是直接扔掉，而是触发一次摘要压缩。

摘要压缩的做法是：当对话轮次达到窗口上限时，把最老的两轮对话交给模型，让它生成一段 100 字以内的摘要，然后把这段摘要插入到系统提示词的一个“历史背景”区域。这样既保留了关键信息，又把 token 消耗降了一个数量级。

interface Message { role: 'user' | 'assistant' | 'system'; content: string; timestamp: number; } class ShortTermMemory { private windowSize: number; private messages: Message[] = []; private summary: string = ''; constructor(windowSize: number = 8) { this.windowSize = windowSize; } async addMessage(msg: Message): Promise<void> { this.messages.push(msg); if (this.messages.length > this.windowSize) { const oldest = this.messages.splice(0, 2); this.summary = await this.compressToSummary(oldest, this.summary); } } private async compressToSummary( msgs: Message[], existingSummary: string ): Promise<string> { // 调用模型生成摘要，实际项目中替换为你的 LLM 调用 const prompt = `已有摘要：${existingSummary}\n新增对话：${msgs .map((m) => `${m.role}: ${m.content}`) .join('\n')}\n请合并为一段不超过100字的摘要，保留关键事实和用户偏好。`; return await callLLM(prompt); } getContext(): Message[] { const context: Message[] = []; if (this.summary) { context.push({ role: 'system', content: `历史对话摘要：${this.summary}`, timestamp: Date.now(), }); } return [...context, ...this.messages]; } }

这段代码的关键在于compressToSummary的提示词设计。我踩过的坑是：早期让模型自由发挥写摘要，结果它把用户随口说的“今天天气不错”也写进去了，真正重要的“用户偏好用 TypeScript 而不是 JavaScript”反而丢了。后来改成明确要求“保留关键事实和用户偏好”，摘要质量才稳定下来。

2.3 长期记忆的存储选型：向量库不是唯一答案

说到长期记忆，很多人第一反应就是上向量数据库。向量库确实好用，但它不是唯一选择，也不一定是最优解。我的经验是：根据记忆的类型分而治之。

用户画像类记忆，比如“用户是前端开发者”“偏好简洁回复”“常用 React 技术栈”，这类信息结构化程度高、数量少、更新频率低，直接用键值对存 Redis 或 SQLite 就够了。检索时全量取出，拼进系统提示词，成本几乎为零。

知识片段类记忆，比如用户之前问过的技术问题、Agent 给出的解决方案，这类信息数量大、需要语义检索，才适合用向量库。我常用的是轻量级方案：本地用 SQLite + 向量扩展，云端用托管的向量检索服务。没必要一上来就搞集群，单机 SQLite 存几万条向量完全够用。

这个分层思路的好处是：不会为了存几十条用户偏好就引入一个向量库的运维成本，也不会为了检索几万条知识片段去写复杂的 SQL 模糊查询。

2.4 记忆写入的时机与去重策略

记忆写入不是每轮对话都写，那样会产生大量冗余。我的做法是设置触发条件：用户明确表达偏好时写入画像记忆；Agent 完成一个完整任务闭环时写入知识片段；对话轮次达到阈值时写入摘要。

去重是个容易被忽略的细节。用户可能在不同会话里反复说“我用的是 React”，如果每次都写一条画像记忆，很快就会积累几十条重复内容。我的去重策略是：写入前先做一次相似度检查，如果已有记忆与新记忆的语义相似度超过 0.9，就更新旧记忆的时间戳而不是新增。向量库一般自带相似度查询，键值对存储的话可以维护一个简单的哈希索引。

注意：去重阈值不要设太高。我试过 0.95，结果“用户用 React”和“用户用 React 18”被判定为不同记忆，其实后者应该覆盖前者。0.85 到 0.9 之间比较合适，具体看你的业务场景。

3. 检索增强：让 Agent 在需要的时候想起该想起的事

3.1 检索时机比检索算法更重要

很多教程一上来就讲 embedding 模型选型、相似度算法、重排序策略，但实际项目里，什么时候触发检索比怎么检索更影响体验。我见过太多 Agent 每轮对话都去检索一遍长期记忆，结果把不相关的信息也塞进上下文，反而干扰了模型判断。

我的做法是分场景触发。用户提问里包含“之前”“上次”“还记得”这类回溯性词汇时，触发长期记忆检索。用户提出新任务时，检索知识片段库里是否有类似任务的解决方案。用户表达偏好时，直接读取画像记忆，不需要语义检索。

这种场景化触发的好处是精准。实测下来，检索命中率比无差别检索高了不止一倍，而且省了大量 embedding 调用费用。前端开发者可以把它理解成事件驱动的状态更新：不是每次渲染都重新计算所有派生状态，而是依赖变化时才计算。

3.2 查询改写：把用户的话翻译成适合检索的形式

用户说“我那个 React 项目又报错了”，直接拿这句话去检索向量库，效果往往不好。因为向量库里的知识片段可能是“React 组件渲染错误解决方案”“React 状态更新异常处理”这类表述，语义上有差距。

查询改写就是解决这个问题的。做法很简单：在检索前，先用一个小模型或规则引擎把用户 query 改写成更适合检索的形式。比如上面那句话可以改写成“React 项目 报错 解决方案”。如果项目里有历史对话，还可以把上下文信息补进去，比如“React 项目 状态管理 报错”。

def rewrite_query(user_input: str, recent_context: list) -> str: # 规则引擎示例，实际项目可替换为小模型 keywords = extract_keywords(user_input) context_hint = extract_tech_stack(recent_context) rewritten = f"{context_hint} {' '.join(keywords)}" return rewritten.strip() def extract_keywords(text: str) -> list: # 简化版关键词提取，实际可用 jieba 等工具 tech_terms = ['React', 'Vue', 'TypeScript', '报错', '性能', '状态'] return [t for t in tech_terms if t in text] def extract_tech_stack(context: list) -> str: for msg in reversed(context): if 'React' in msg.get('content', ''): return 'React' if 'Vue' in msg.get('content', ''): return 'Vue' return ''

这段代码很粗糙，但思路是对的：把用户口语化的表达转成检索友好的关键词组合。我实测过，加了查询改写之后，检索到的知识片段相关性明显提升，Agent 给出的回答也更贴合用户实际场景。

3.3 检索结果的重排序与截断

向量检索返回的 top-K 结果，相似度分数高不代表一定有用。我遇到过检索出十条结果，前三条都是同一篇文档的不同片段，内容高度重复。直接塞进上下文，既浪费 token 又稀释了有效信息。

重排序的做法是：对检索结果做一次去重和多样性检查。如果多条结果来自同一来源，只保留相似度最高的一条。如果结果之间语义相似度超过阈值，也做合并。最后按相似度排序，取前 N 条，N 一般取 3 到 5。

截断策略也很关键。每条检索结果不要全文塞入，而是截取与查询最相关的段落。向量库一般支持返回匹配的 chunk，如果用的是全文检索，可以按关键词位置截取前后各 200 字。这样能把单条结果的 token 消耗控制在 300 以内。

3.4 把检索结果自然融入上下文

检索到的记忆怎么放进提示词，也是有讲究的。直接拼接在用户消息前面，模型可能分不清哪些是历史记忆、哪些是当前问题。我的做法是用明确的分隔标记，并且在系统提示词里说明这些标记的含义。

比如系统提示词里加一段：“以下内容是从长期记忆中检索到的相关信息，供你参考，但不要直接复述，而是结合当前问题给出回答。”然后用<memory>标签包裹检索结果。这样模型能清楚知道这部分内容的定位，不会把记忆里的内容当成用户当前说的话。

实测下来，这种显式标记比隐式拼接的准确率高不少。尤其是当检索结果与当前问题只有部分相关时，模型能更好地判断哪些该用、哪些该忽略。

4. 遗忘机制：为什么“记住一切”反而是灾难

4.1 记忆衰减的必要性与实现方式

刚开始做记忆系统的时候，我恨不得把所有东西都记下来。结果跑了两个月，向量库里堆了几万条记忆，检索出来的结果越来越杂，Agent 的回答反而变得啰嗦且不准确。后来才明白：记忆系统跟人脑一样，需要遗忘。

遗忘不是简单删除，而是按重要性和时效性做衰减。我的做法是给每条记忆打两个分数：重要性分数和新鲜度分数。重要性由写入时的场景决定，比如用户明确表达的偏好重要性高，Agent 自动生成的摘要重要性中等。新鲜度随时间衰减，但衰减速度不一样：用户画像衰减慢，任务状态衰减快。

检索时，最终得分是相似度、重要性、新鲜度的加权和。这样即使一条记忆语义相似度很高，但如果太旧且不重要，也不会被检索出来。权重怎么定？我的经验是相似度占 0.6，重要性占 0.25，新鲜度占 0.15。这个比例可以根据业务调整，但相似度必须占主导，否则检索就失去意义了。

4.2 记忆合并与抽象升级

比遗忘更高级的操作是合并与抽象。用户在不同时间说了“我用 React”“我主要写前端”“我的项目是 Next.js”，这三条记忆可以合并成一条更抽象的记忆：“用户是前端开发者，技术栈为 React 和 Next.js”。合并之后，记忆数量减少了，但信息量没有损失，检索效率反而更高。

实现上，可以定期跑一个后台任务，把相似度超过阈值的记忆聚类，然后让模型生成合并后的抽象记忆。这个任务不需要实时跑，每天或每周执行一次就行。我一般放在低峰期，用便宜的模型来做，成本可控。

抽象升级则是把具体事件升级为模式。比如用户连续三次问的都是“React 性能优化”相关问题，就可以抽象出一条“用户关注 React 性能优化”的画像记忆。这样下次用户再问类似问题，Agent 能直接调用这条画像，而不需要检索三次具体对话。

4.3 记忆冲突的处理策略

冲突是难免的。用户上个月说“我用 Vue”，这个月说“我转 React 了”。两条记忆都存着，检索时可能同时返回，模型就懵了。处理冲突的核心原则是：新记忆覆盖旧记忆，但保留变更历史。

具体做法是：写入新记忆时，先检索是否有语义冲突的旧记忆。如果有，把旧记忆标记为“已过期”，并记录新记忆的生效时间。检索时默认只返回未过期的记忆。如果用户明确问“我之前用什么技术栈”，才把历史变更也返回。

前端开发者可以类比成状态管理里的“乐观更新 + 回滚记录”：当前状态以最新为准，但操作日志保留着，需要时可以回溯。

提示：冲突检测不要做得太激进。用户说“我最近在学 Rust”不代表他放弃 React 了，这两条记忆可以共存。只有明确表达“转”“换”“不再用”这类变更意图时，才触发覆盖逻辑。

5. 工程落地：从原型到稳定运行的几个关键决策

5.1 记忆系统的性能瓶颈在哪里

跑通原型之后，性能问题会逐渐暴露。我实测下来，瓶颈通常不在向量检索本身，而在 embedding 计算和上下文组装。每次写入记忆都要调 embedding 接口，如果同步执行，会明显拖慢对话响应速度。上下文组装时如果检索结果太多，拼接字符串也会消耗时间。

优化方案是异步化。记忆写入走消息队列，不阻塞主对话流程。embedding 计算可以批量处理，攒够一批再统一调用。上下文组装时设置硬性 token 上限，超过就截断，保证响应时间可控。

另一个容易忽略的点是向量库的索引更新。如果用的是内存型向量库，每次重启都要重新加载全部向量，数据量大时启动很慢。我的做法是定期把向量持久化到磁盘，启动时从磁盘加载，同时后台异步更新增量部分。

5.2 多用户场景下的记忆隔离

单用户 Demo 跑通后，下一步就是多用户。这时候记忆隔离必须做好，否则 A 用户的偏好被 B 用户检索到，就是严重的事故。隔离方案有两种：物理隔离和逻辑隔离。

物理隔离是每个用户一个独立的向量库集合或独立的表。好处是彻底隔离，坏处是用户多了之后管理成本高。逻辑隔离是所有记忆存在一起，但每条记忆带user_id字段，检索时强制过滤。我倾向于逻辑隔离，因为实现简单，而且大多数向量库都支持元数据过滤。

关键是过滤条件必须强制加上，不能依赖调用方自觉。我会在记忆服务的入口层做统一拦截，所有查询自动注入当前user_id，业务代码不需要关心隔离逻辑。这样即使后续有新的检索入口，也不会漏掉隔离。

5.3 记忆系统的可观测性建设

记忆系统出问题往往很隐蔽：Agent 回答变差了，但你不知道是检索没召回、还是召回了但没用好、还是记忆本身写错了。所以可观测性必须提前建设。

我一般会记录几个关键指标：每轮对话的检索命中数、检索结果的平均相似度、记忆写入量、记忆总量、检索耗时。这些指标打到日志或监控系统里，出问题时能快速定位。比如检索命中数突然降到零，可能是 embedding 服务挂了；相似度普遍偏低，可能是查询改写出了问题。

还有一个实用技巧：在开发环境里把每轮对话实际使用的记忆内容打印出来。这样调试时能直观看到 Agent “看到”了什么，比看日志高效得多。

5.4 成本控制：记忆系统的隐形开销

记忆系统的成本不只是模型调用。embedding 计算、向量存储、检索查询都有开销。我算过一笔账：如果每轮对话都写入记忆并计算 embedding，按每天 1000 轮对话算，一个月的 embedding 费用可能比对话本身的模型费用还高。

控制成本的关键是减少不必要的写入和检索。写入方面，不是每轮对话都值得记，只有包含偏好、任务闭环、重要事实的对话才写入。检索方面，不是每轮都检索，按前面说的场景化触发。另外，embedding 模型不一定要用最贵的，很多开源小模型在短文本上的表现足够好，成本却低一个数量级。

这套组合拳下来，我的实测成本降低了大约 70%，而 Agent 的表现反而更稳定了。因为上下文更干净，模型注意力更集中。

6. 几个真实踩坑记录与排查思路

6.1 检索结果明明相关，Agent 却视而不见

这个问题困扰了我很久。检索日志显示召回了正确的记忆，相似度 0.92，但 Agent 的回答完全没用到。排查过程是这样的：先确认检索结果确实进入了上下文，打印出来一看，确实在。然后检查提示词，发现检索结果被放在了用户消息之后、系统提示词之前，模型可能把它当成了用户输入的一部分，而不是参考信息。

调整位置后问题解决。检索结果应该放在系统提示词区域，或者用明确的分隔标记包裹，并且系统提示词里要说明这部分内容的用途。位置和标记方式对模型的影响比想象中大。

6.2 记忆写入越来越多，检索越来越慢

跑了三个月后，向量库从几千条涨到几万条，检索延迟从 50ms 涨到 500ms。排查发现两个问题：一是没有做记忆合并，大量语义重复的记忆堆积；二是向量索引没有定期重建，碎片化严重。

解决方案是加了一个定时任务，每周做一次记忆合并和索引重建。合并后记忆数量减少了约 60%，检索延迟回到 80ms 左右。这个任务放在凌晨执行，对线上服务没有影响。

6.3 用户反馈“Agent 怎么老提我以前说过的话”

这是记忆过度使用的典型症状。Agent 为了展示“我记得你”，频繁引用历史记忆，反而让对话变得不自然。根因是检索触发太频繁，而且检索结果没有做相关性过滤。

修复方式是提高检索触发门槛，只在用户明确回溯或当前问题确实需要历史信息时才检索。同时给检索结果加一个相似度下限，低于 0.75 的直接丢弃。调整之后，Agent 的表现自然多了，该记的记，该忘的忘。

6.4 多轮对话中记忆被反复覆盖

有个场景是用户连续补充需求，每补充一次就触发一次记忆写入，结果后面的记忆把前面的覆盖了，最终只保留了最后一条。排查发现是冲突检测逻辑太激进，把“补充”误判成了“变更”。

修复方式是区分“追加”和“变更”。用户说“还有一点”“另外”时，走追加逻辑，新记忆与旧记忆合并而不是覆盖。只有明确说“改成”“换成”时才走覆盖逻辑。这个判断可以用简单的规则引擎做，准确率足够。

7. 记忆系统后续可以怎么演进

把上面这套跑通之后，Agent 的连续对话体验会有质的提升。但记忆系统本身还有很多可以深挖的方向。比如记忆的主动回忆：Agent 在回答前主动判断“这个问题我是不是该查一下记忆”，而不是等用户说“你记得吗”。再比如跨模态记忆：不只记文本，还记用户上传的图片、文档的结构化摘要。

另一个方向是记忆的共享与协作。多个 Agent 之间共享部分记忆，比如一个团队里的多个助手共享团队知识库，但各自保留用户私有记忆。这在多 Agent 协作场景里会越来越重要。

我现在手上的项目已经在尝试记忆的优先级队列：把最重要的记忆常驻在上下文里，次要的按需检索，边缘的定期清理。效果还在观察，但初步看比纯检索方案更稳定。如果你也在做类似的事情，欢迎交流踩坑经验。记忆系统这东西，没有一劳永逸的方案，只有不断迭代的平衡。