ai-memory 算是我最近手头最折腾的一个侧项目。起因很简单我做了一个基于语言模型的问答助手第一版一问一答很顺但只要用户隔几天再回来它就完全变成陌生人连之前聊过的话题、做过的选择、记过的偏好都忘得一干二净。这个痛点相信不少人在做客服机器人、个人助理、智能体Agent或者是任何需要连续对话的产品时都撞上过而 ai-memory 这个项目就是专门解决这个记不住事的问题。说白了这个项目要做的不是单纯的日志记录而是给 AI 设计一套可检索、可更新、可遗忘的记忆机制。让它在新的对话里能主动调取历史经验同时又不让垃圾信息把上下文窗口塞爆。这篇文章我把自己从方案选型、数据建模、代码实现到踩坑排查的完整过程整理出来适合正在做对话机器人、知识库问答、智能体工作流的开发者参考。如果你只是想给自己的个人助手加一点人性化的长期记忆这里面的大部分思路也可以直接抄作业。1. 项目背景与设计思路拆解1.1 为什么 AI 需要一套显式的记忆层很多人会觉得对话模型天生就知道很多事那记忆应该也不是问题吧实际跑过就明白模型本身并不具备跨会话记忆能力。每次对话开始时它都是一张白纸只依赖你当前喂给它的上下文。哪怕你上一个会话里聊得再深入这个会话一结束信息就散了。有一种朴素的解法是把所有历史消息都拼进新请求里。这种方案在几十条消息内勉强能用但消息一多就会出现几个问题上下文窗口被占满、模型注意力被无关信息稀释、Token 费用直线上升。我一开始就试过这条路结果项目还没跑起来光看账单就已经想放弃了。真正靠谱的做法是仿照人脑的工作方式把记忆分成不同层级正在讨论的细节放工作记忆相对重要的长期事实放进长期记忆而一些临时性的、过期掉的内容则应该有意识地遗忘。ai-memory 这个名字虽然起得很直白但它承载的核心逻辑就是这么一套分层处理框架。项目里我把它具体做成了三个模块记忆写入端、记忆存储与索引、记忆召回端分别对应你看到一个信息时决定记不记、记在哪、以及未来怎么把它想起来。1.2 记忆分层与方案选型在动手写代码之前我花了不少时间纠结选型。要在对话场景里做记忆常见的有几种路线纯文本文件存聊天记录、SQLite/MySQL 存结构化字段、向量数据库做语义检索、知识图谱做实体关系管理。老实说没有一种方案是万能的最后还是要根据场景组合着用。我最终的方案是这样拆分的记忆层承担职责推荐载体取值逻辑短期记忆当前会话内的上下文内存缓存会话 ID 维度过期清理长期事实记忆用户偏好、关键事实、明确的结论结构化存储抽取关键信息去重合并语义记忆历史片段与当前提问的模糊匹配向量索引Embedding 相似度召回程序性记忆用户的操作习惯、流程偏好规则或配置统计行为模式后固化这套分层的本质是把每条信息都塞进上下文改成按需取用。短期记忆负责兜底长期记忆负责稳定事实向量索引负责做类比和联想。知识图谱我没有在第一版就用上因为它的维护成本实在不低但对于强关系类的场景比如用户 A 的老板是 B项目 C 和 A 无关图谱的推理能力是纯向量方案比不了的。我现在的建议是先跑通向量 结构化的组合真正遇到关系推理瓶颈再考虑引入图谱。1.3 设计上的三个关键约束动手之前我给自己定了三条设计约束后来的实践证明非常有用。第一是记忆必须可追溯。每条记忆都要能追溯到来源消息和时间戳否则召回出来的东西一旦出错根本没法排查。第二是必须允许遗忘。没有遗忘机制的记忆系统就是一个垃圾场跑不了多久就会出现大量互相矛盾或早已过期的条目。第三是隐私要可控。涉及用户原始对话内容时我不会把敏感原文直接丢进长期库而是尽量转化为抽象的事实描述。这三条约束直接影响了后面的数据模型设计和接口规划。比如可追溯就要求我在消息元数据里带 session_id 和 original_message_id允许遗忘就要求我在存储层做一个 TTL 字段和冲突检测逻辑。这些都是最容易被新手忽略、但后期返工代价极高的点。2. 核心细节解析与实操要点2.1 记忆数据怎么建模才不会乱记忆的第一版我偷懒直接用 CSV 存聊天记录。字段就是谁说的、说了啥、什么时候说的写完一跑就发现问题召回的时候完全不知道哪条信息该优先也很难判断两条记录是不是在讲同一件事。后来我重新设计了记忆条目的数据模型每一个记忆项都写成一个结构化的 JSON 对象{ memory_id: mem_7f3a2b1c, namespace: user_skylar, content: 用户目前住在杭州工作与数据开发相关, source_type: chat, source_ref: session_9f2e, importance: 8, confidence: 0.92, created_at: 2025-01-14T10:32:00Z, accessed_at: 2025-01-15T09:20:00Z, access_count: 3, ttl: null, embedding_ref: vdb_8a1c21 }这个结构里有几个字段是我后来调优时渐渐加进去的。importance表示这条记忆的重要程度取值范围 0 到 10它决定了召回时是否优先展示confidence表示这条信息的可信度来自模型抽取时给的概率access_count和accessed_at则负责记录这条记忆多久没被用过了用来做末尾淘汰。写的时候可能看不出这几个字段有什么用但在线上跑一阵子就会发现没有它们整个记忆库就是一堆无法排序、无法清理的死数据。特别是namespace这个字段能让你在同一套代码里同时服务多个用户或机器人角色而不会互相串味。2.2 写入时机与更新策略记忆不是越多越好写入时机决定了整个系统的上限。我早期做的时候只要能抽到内容就写结果十天之后记忆库里全是用户今天吃了个汉堡这种噪音真正有用的偏好反而被淹没了。后来我把写入策略调成了三层过滤第一层是新鲜度过滤。临时性、时效性很强的信息只放短期记忆比如用户这周在追某部剧剧追完这条就没用了第二层是重要性过滤。只有被判定为重要性大于等于 6 的内容才允许进入长期记忆库第三层是冲突检测。如果新信息和旧信息矛盾比如用户之前说喜欢甜口这次说喝咖啡不加糖了就不要盲目追加而是判断哪条更新、哪条可信度更高。具体到执行层面我会把模型抽取结果里的importance和confidence都返回出来再写一段小逻辑做合并。举个例子如果新条目和旧条目的文本相似度超过 0.85且新条目重要性和可信度都更高我就直接替换旧条目同时保留新旧两版的履历链。这样做的好处是未来即使用户再次改变主意我也能查到他是怎么变的而不是看到一条凭空冒出来的矛盾记录。2.3 召回策略里的分寸感记忆召回是另一个非常考验分寸的地方。召回太少AI 表现得像失忆召回太多上下文被无关信息污染。我参考了搜索系统里的做法在召回模块里组合了两路信号一路是向量相似度用它判断语义上的相关性。另一路是结构化过滤比如用户 ID、时间衰减、重要性加权。最后用一套加权公式把分数汇总取 top-K 个结果拼进提示词。我实际用的公式大概是这样的final_score 0.55 * vector_similarity 0.30 * importance_norm 0.15 * recency_factor这里的importance_norm是把重要性除 10 得到的归一化分数recency_factor则根据accessed_at距今的时间做指数衰减。这套公式不复杂但比单纯按相似度召回的效果好很多因为用户偏好类的记忆往往在语义上和当前问题的关联并不强反而需要靠重要性和新鲜度来兜底。召回结果再往后就是要不要拼进提示词的问题。我发现全部塞进提示词会让系统过度应激动不动就引用旧话题。后来我加了一个约束只有当召回结果的相关度大于某个预设阈值时才进入上下文否则宁可不命中也不要让模型硬把无关信息编进去。这个阈值我在中文场景下调得比较保守大概在 0.6 左右偏低容易引入噪音偏高又容易漏召回需要根据自己的场景反复调。3. 实操过程与核心环节实现3.1 存储层的实现选择存储层我换过一次方案。第一版用 JSON 文件直接落盘方便是方便但每次检索都是全量遍历几十条记录还能忍到了几百条就明显降速更别提并发访问时的文件锁问题。后来我把数据拆成两部分结构化元信息放 SQLitetext 字段的语义向量单独放到向量数据库里。SQLite 这边我建了一张叫memory_items的表核心字段如下CREATE TABLE memory_items ( memory_id TEXT PRIMARY KEY, namespace TEXT, content TEXT, source_type TEXT, source_ref TEXT, importance INTEGER, confidence REAL, created_at TEXT, accessed_at TEXT, access_count INTEGER, ttl TEXT, embedding_key TEXT ); CREATE INDEX idx_memory_namespace ON memory_items(namespace); CREATE INDEX idx_memory_created ON memory_items(created_at);SQLite 的好处是零部署、单文件、训练成本低。对于个人项目或者中小体量的聊天机器人它完全够用。如果未来数据量真的大到 SQLite 扛不住可以直接把表结构迁到 PostgreSQL接入pgvector做统一查询代码层面改动不会太大。至于向量数据库我用的是 Chroma主要是看中它有嵌入式模式不需要额外起服务只要在你的项目目录里指定一个持久化路径重启后数据依然在。3.2 一条完整的写入-召回链路我这里给一个简化的核心链路实现读者可以把它直接当作脚手架再扩展。输入是一次对话消息输出是这一次消息里是否要写入记忆以及下一次提问时的召回结果。先看写入端的核心函数import uuid from datetime import datetime, timezone def extract_memory_from_message(message_text, session_id, model_client): prompt f 判断用户的这句话里是否有值得长期记住的信息。 用户说{message_text} 如果没有返回 empty。 如果有输出 JSON字段包含 content, importance(0-10), confidence(0-1) result model_client.complete(prompt) if empty in result.lower(): return None parsed json.loads(result) return { memory_id: str(uuid.uuid4()), content: parsed[content], importance: parsed[importance], confidence: parsed[confidence], source_ref: session_id, created_at: datetime.now(timezone.utc).isoformat(), }写入端抽完内容之后会先做一次冲突检测把新内容的向量去库里做一遍相似度查询如果 top1 相似度高于 0.85就执行合并或替换否则插入新条目。这个逻辑把乱写的门槛挡掉了一大半。再看召回端的核心函数def recall_memories(query, namespace, db, vector_index, top_k5): query_emb vector_index.embed(query) candidates vector_index.search(query_emb, top_k, namespacenamespace) results [] for cand in candidates: meta db.get_memory(cand[memory_id]) if meta is None: continue score 0.55 * cand[similarity] 0.30 * (meta[importance] / 10) 0.15 * recency(meta[accessed_at]) results.append((score, meta)) results.sort(keylambda x: x[0], reverseTrue) return [meta for score, meta in results[:top_k]]召回端做的事说白了就是两路数据合并打分。实际项目里我建议把top_k设成 5 到 8 之间太少容易漏关键信息太多则会让提示词变得臃肿。另外每次召回命中之后记得把accessed_at更新一下否则后面做记忆淘汰时所有旧数据都会因为时间衰减变成低分造成冷门信息永无翻身之日的恶性循环。3.3 参数选择与效果调优我给这版核心代码配了几组关键参数这里分享一组在中文对话场景下实测效果比较稳定的配置参数名推荐值备注Embedding 模型bge-small-zh 或 text2vec-base中文场景建议用中文向量模型文本切片长度200 字符切片太长召回精度下降切片重叠30 字符避免语义断在切片边界记忆重要度阈值6 分低于 6 分不进长期库向量召回 top_k5太长会稀释注意力相关度阈值0.6低于阈值不拼进提示词记忆 TTL30 天未命中即淘汰长期偏好除外这个组合不是绝对标准但它是我跑了多轮对比之后比较稳定的一个点。例如切片长度是 200 字符而不是 400 字符是因为 400 字符会造成单条向量里包含太多意图召回的片段和实际问题不够精准而 100 字符又太碎经常把一段话的前后逻辑撕裂。调参的过程中我没有用很复杂的自动搜索主要靠一批人工构造的测试问题来回归验证。每次调完参数就问几个典型问题比如用户上次说想去哪个城市他最喜欢的配色是什么他最近换工作了没有看召回结果是否落在预期范围内。这类测试集不用太大二十条就够了但覆盖面要广最好包含偏好、状态、临时事件、关系类四种类型。4. 常见问题与排查技巧实录4.1 高频故障与解决速查这个项目跑起来之后我踩了不少坑。这里整理一张速查表把最常见的几个问题和对应解法记录下来方便遇到类似情况的朋友直接对照处理。现象可能原因解决思路模型完全想不起旧信息召回阶段相关度阈值设太高检查阈值适当降一点模型总是引用无关旧事重要性权重过低噪音压制关键词召回提高重要性加权给噪音打低分记忆库里存在大量矛盾记录缺少冲突检测逻辑在写入前做相似度匹配和版本替换上下文窗口仍然被占满拼进提示词的记忆条数太多把 top_k 降到 5或压缩记忆内容格式中文召回效果明显变差使用了英文原版向量模型换成中文 Embedding 模型数据量一多就卡顿SQLite 没有建索引添加namespace和created_at索引记忆库膨胀失控没有淘汰机制增加 TTL 字段和定期清理任务这里面我特别想强调的就是模型总是引用无关旧事这个问题。它通常不是因为模型记忆太好而是因为召回结果里的低频但高相似度的噪音把真正重要的偏好挤掉了。解决办法不是删数据而是调高importance在加权公式里的比例同时给access_count低、同一条记忆连续多次未被命中的条目降温。4.2 排查记忆类问题的方法论排查这类问题最忌讳的就是盯着一次对话结果猜来猜去。我的习惯是先把记忆库的状态导出来看看比如用一条命令查一下当前库里到底存了什么数据SELECT content, importance, confidence, access_count FROM memory_items WHERE namespace user_skylar ORDER BY importance DESC LIMIT 20;如果召回结果异常第一步永远是确认到底有没有存对。很多问题的根源根本不在召回算法而在于写入端就把话听错了存了半截信息或者干脆存了错误结论。所以排查顺序应该是先检查原始消息有没有进库再检查抽取出来的记忆内容对不对然后检查向量检索返回的相似度是否合理最后才谈得上调整加权公式。另一个很有用的调试技巧是在召回回传的上下文里手动打一条 Debug 日志把每条召回记忆对应的similarity、importance和recency_factor全部打印出来。这样你能直观看到到底是哪个环节把分数拉低或者拉高了。我后来甚至做了个小工具把所有召回候选按最终分排序并列出来标红命中项。这样每次调参都有了可视化依据而不是闭着眼瞎调。4.3 记忆冲突的特殊处理记忆冲突是长期跑这个系统绕不开的问题。用户上个月说不爱吃香菜这个月说重庆火锅真香你怎么判断我采用的策略是时间优先原则。当新旧信息冲突时默认采用时间更新的那条同时保留旧版本的历史痕迹。但如果两条冲突信息的时间非常接近那就需要看模型抽取时的置信度。置信度更高的那条通常是用户表达更明确的信息应优先保留。这个案例我建议在记忆数据结构里专门加一个supersedes字段记录它替换掉了哪条旧记忆否则一旦 AI 说错话你连它是被哪条错误信息误导的都查不出来。5. 影响范围与后续扩展路径5.1 典型落地场景拆解ai-memory 这套方案虽然不是那种能直接发布的产品但它的影响范围可以覆盖到很多实际业务中。第一个典型场景是智能客服。客服的核心痛点就是用户每次都要从头解释一遍自己的问题。接入记忆系统之后用户报一次单号之后每次对话就不需要再重复了客服也能根据历史订单和偏好给出更有针对性的答复。第二个场景是个人知识库问答。很多人用在线笔记或者本地 Markdown 文件构建知识库但传统的关键词搜索查不出语义相似的内容。把知识切片向量化并配上记忆层之后提问我之前想过一个用 Python 做报表自动化的思路就能直接命中那篇几个月前的笔记。第三类是虚拟角色或陪伴类应用这类产品对连续性的需求最高角色如果能记住用户爱听的称呼、聊过的话题、情绪变化体验完全是两个等级。5.2 工程上的后续扩展方向就我目前跑下来的感受这个项目最值得继续扩展的方向有两个。一个是把记忆管理做成 Agent 的可调用工具。传统的记忆是系统自动写入、自动召回但有时候模型需要主动想起某件事或者更新某个认知这时候提供一个记忆检索 API 给 Agent 去调用反而比自动拼上下文更可控。另一个方向是做事件驱动的记忆处理。比如监测到用户修改了个人信息、完成了某个长期目标、或中断了一个长时间未完成的计划这些都能触发记忆库的更新动作。我现在正在把 ai-memory 接入自己的消息队列让写入端异步化避免每一条消息都阻塞主对话链路。实测下来响应延迟对用户体验是有明显改善的。关于受影响范围的另一个值得注意的点是记忆系统不应该只服务对话模型。它还可以服务推荐系统、搜索系统、甚至运维排查系统。只要你有一个需要跨时间记住上下文的场景这套分层记忆的设计思路都可以平移过去。这意味着 ai-memory 并不是一个只能活在聊天机器人里的玩具项目而是一个有复用价值的中间件原型。这个项目真正让我觉得值得做的地方不是因为技术有多复杂而是它揭示了一个容易被忽视的问题AI 的能力不仅取决于模型本身还取决于它能不能高效地组织和使用自己的经验。给我的体会是做记忆系统最重要的不是追求存储得多或召回得多而是把存储、召回、遗忘、冲突处理这几件事平衡好。最后分享一个我实际操作中的小技巧给每个记忆条目都保留一条最近一次被使用的时间和次数记录每隔两周跑一次清理任务。你不需要什么高深算法就按access_count和ttl把从没被用过、又已经过期的数据删掉整个系统会感觉清爽很多。记忆存储这件事我现在的原则一直是一句话好记忆是在对的时候想起对的事而不是把磁盘铺满。