1. 这个项目是从一次“失忆事故”开始的我一直在做 AI Agent 类应用最早踩过的坑不是模型能力不够而是对话历史一长Agent 就开始“精神分裂”。同一个用户上周明确说过用的是 PostgreSQL 16这周问它数据库版本它能一本正经地告诉你 MySQL 8.0昨天刚让 Agent 记住“不要用某个第三方支付渠道”今天它又把人引导到那个渠道去注册。这类问题的根源不是提示词写得不好而是当时我把所有记忆都塞在上下文窗口里。窗口有上限新对话一进来旧内容就被挤掉Agent 只能基于最近几轮对话做判断。后来我试过把历史记录直接拼进 system prompt结果 token 消耗直接翻倍响应延迟变高效果却依然不稳定——关键信息被淹没在大量日志和无关闲聊里了。我开始认真思考“长期记忆”到底该怎么落地。这里说的长期记忆不是 Redis 里存一堆 session也不是把历史消息原封不动存进数据库而是让 Agent 能像人一样区分“随口说的一句话”和“值得记住的偏好”能在需要的时候主动想起某条旧信息并且能根据新信息修正之前记错的内容。看了一圈现成方案当时主流的记忆插件大多做的是“近期对话摘要 向量检索”本质还是把历史文本切块后塞进向量库。这种做法对简单问答够用但对真正需要长期运营的 Agent 场景远远不够没有记忆分级、没有冲突处理、没有遗忘机制、没有对“哪些信息值得写入长期存储”的判断。后来我接触到 OpenViking这个项目打动我的地方在于它不把自己定位成又一个向量数据库而是把记忆当成有一等公民地位的系统来设计。它提供了一套分层记忆框架短期会话记忆、工作记忆、长期语义记忆彼此分离又通过事件流串起来配合检索策略和记忆生命周期管理。这篇文章就记录我基于 OpenViking 搭建 AI 长期记忆系统的完整过程。适合已经在做 Agent 应用、并且对“上下文一长就崩”这件事有切肤之痛的人参考。如果你是第一次接触记忆系统设计也能从文章里看到一套完整的架构思路。2. OpenViking 做的事先给记忆建模再做检索先说一个反直觉的结论长期记忆系统的瓶颈通常不是存储而是写入策略和检索精度。存储无非是向量库或者混合数据库方案成熟真正难的是决定“什么该记、什么不该记、同一件事有了新说法该怎么办、什么时候该把旧记忆翻出来”。OpenViking 相比我前面提到的通用记忆工具最大差异就是它把这些问题全部收口成了可配置的管道而不是留给你自己写一堆散落的逻辑。2.1 它不是一个“更大的向量库”很多团队的误区是只要把向量库容量做大上下文不够的问题就解决了。实际上如果你只是把历史消息切块、向量化、存起来检索时一定会遇到两类问题噪音太多。历史消息里大量内容是“嗯”“好的”“稍等”“我看看”这类无意义文本把它们向量化之后检索结果往往被这些碎片污染真正有价值的用户偏好反而不容易召回到。语义冲突。用户星期一告诉你“我习惯用邮箱接收报告”星期四又改口“还是发企业微信吧”。如果你不做冲突处理最后一次检索时两条信息都会返回Agent 会陷入自相矛盾。OpenViking 的做法是先结构化记忆对象再决定如何存储和检索。它把记忆抽象成标准的记忆记录每条记录自带类型、来源、时间戳、重要度和状态字段写入前要经过抽取和清洗而不是直接把原文丢进向量库。这个设计让后面所有策略都变得可控。2.2 分层记忆的具体划分这套系统把记忆分成三层我把它理解成“便利贴、工作台、档案馆”的关系。短期记忆对应会话上下文Agent 处理当前请求时能立即看到类似便利贴随时可丢弃。工作记忆是当前正在进行但尚未完结的任务状态比如用户正在填写一份多步骤表单填到哪一步了、已经提供了哪些字段这些信息要在几步之内持续生效。长期记忆才是真正需要沉淀的内容用户的基本属性、长期偏好、历史结论、领域知识、项目约束等。OpenViking 的工作机制是短期记忆和工作记忆在会话内快速流转系统通过事件流异步抽取其中有价值的部分转换成语义记忆或情节记忆写入长期层。读取的时候则反过来先根据当前上下文判断需要哪些长期记忆再定向检索、注入工作记忆区。这种设计让每次请求只需要携带与当前任务相关的记忆而不是把完整历史都灌进上下文。2.3 记忆不是孤立文本而是带关系的事件我在没看 OpenViking 源码之前以为它只是个向量库封装。真正深入之后才发现它最有价值的部分是“记忆对象模型”。以用户说过的一句话为例普通做法是直接 embedding 这一句话OpenViking 会把它解析成一条结构化记忆大致包括这几个维度实体这是关于谁/哪个项目的记忆属性或关系该实体有什么特征或者和另一个实体有什么关系情感/态度用户表达的喜好取向喜欢、不喜欢、无感时间该信息从什么时候开始生效置信度是用户明确说出的还是系统从行为里推断的这样一条记忆记录存储下来后面做冲突检测、时效判断、定向检索都能落到具体字段上而不是对着整段文本做模糊匹配。比如“我不用某某支付”这样的信息会被打上约束条件的标签当 Agent 后续准备调用支付工具时约束过滤这一层就能把它准确拦截下来。所以说OpenViking 的价值更接近“记忆中间件”。它负责记忆的抽取、结构化、分层存储、生命周期管理、检索注入。向量库只是它底层的一个组件你完全可以在它下面接不同的存储引擎。3. 如何建模“长期记忆”我的 Schema 设计与配置实践在真正写代码之前我花了两天时间梳理数据模型。这个过程不能省因为记忆对象模型设计得好不好直接决定后面冲突处理、定向检索能做到多精细。3.1 记忆记录的核心字段我最终在 OpenViking 体系里用的记录结构大致长这样用 JSON 示意{ memory_id: mem_8f3a2c1e, type: semantic, scope: user_1001, entities: [user_1001, payment_provider_x], relation: dislikes, content: 用户明确表示不想用 payment_provider_x 进行支付, constraints: [checkout_flow], importance: 0.92, confidence: explicit, created_at: 2025-06-14T10:22:31Z, last_accessed_at: 2025-06-15T09:00:00Z, status: active, source_event_ids: [evt_8821] }字段解释如下type 分 semantic / episodic / procedural 三类。semantic 是用户偏好、事实性知识episodic 是具体发生过的事件比如“上周三用户反馈过登录页面超时”procedural 是流程性记忆比如“处理退款时必须先核验订单状态”。importance 是重要度评分0 到 1。写入时由抽取模型评估系统定期重新计算长时间未被访问且重要度低的记忆会被降级甚至归档。confidence 表示这条记忆是用户显式告知的还是系统推断的。显式记忆优先级更高推断记忆允许被后续行为推翻。constraints 是我自己扩展的字段用来标记这条记忆在哪些流程上下文中必须被考虑。这个字段在后面做“功能上下文过滤”时特别好用。3.2 配置文件实例OpenViking 的配置采用 YAML 文件核心是定义抽取模型行为、存储后端、检索策略和生命周期策略。下面是我调过一段时间后的可用配置memory: storage: provider: qdrant collection: long_term_memories embedding_model: text-embedding-3-small dimension: 1536 extractor: provider: openai model: gpt-4o-mini enabled_types: [semantic, episodic] min_text_length: 8 extract_interval_seconds: 15 retrieval: top_k: 8 score_threshold: 0.42 diversity_penalty: 0.35 enable_rerank: true lifecycle: default_importance: 0.55 access_decay_days: 30 archive_threshold: 0.25 conflict_check: true agent_injection: max_tokens: 1200 format: relevant_memories几个容易忽略的配置点extractor 的 extract_interval_seconds 控制异步抽取线程多久跑一次。太短会增加模型调用成本太长会导致短期信息还没入库就被后续内容淹没。我用 15 秒是比较平衡的值。retrieval 里的 diversity_penalty 值得单独说一下。如果只按相似度取前 k 条返回来的记忆往往集中在同一个话题加入多样性惩罚后检索结果会更分散能覆盖用户当前可能需要的多个侧面。实测对复杂任务帮助明显。lifecycle 里的 access_decay_days 表示记忆如果超过 30 天未被访问重要度就开始衰减。这个机制很关键没有遗忘机制的记忆库最终会堆满噪声。4. 部署 OpenViking容器编排、初始化与三个坑4.1 快速启动的编排方式我用 docker compose 一次性拉起整套依赖。OpenViking 本身是无状态的服务进程真正有状态的是向量库、事件总线和元数据库。我的 compose 文件主要包含四个服务OpenViking API 服务、Qdrant 向量库、PostgreSQL存事件源和记忆元数据、Redis短期工作记忆的缓存层。第一次启动之后需要执行初始化动作openviking init --config ./openviking.yml openviking index create --collection long_term_memories --dimension 1536 openviking webhook register --endpoint http://my-agent-service/memory-events这里解释一下第三条命令的含义。OpenViking 支持被动写入和主动注册两种方式。被动写入是让 Agent 调用 SDK 显式上报事件主动注册是给 OpenViking 配置一个 webhook它会监听 Agent 系统的对话事件流自动抽取并沉淀记忆。我在早期版本用的是主动注册方式让 OpenViking 定期从消息服务拉取新对话再由抽取模型异步生成记忆。这样 Agent 业务代码里不需要埋太多记忆写入逻辑解耦性最好。4.2 坑一Embedding 模型维度不一致导致索引重建我在部署第一天就踩了索引维度冲突。OpenViking 的底层索引初始化成功之后我又换了 embedding 模型新模型输出 1536 维但集合还是按旧模型 768 维创建的结果查询时直接报 shape mismatch。这个问题的根因是 Qdrant 这类向量库不允许动态修改已创建集合的向量维度。当时排查了挺久最后只能删集合重建花了半小时重新灌数据。后来我学乖了在配置里显式锁定 embedding_model 版本任何模型升级都走迁移流程而不是原地改配置。4.3 坑二抽取线程阻塞导致记忆写入延迟系统刚跑起来时我注意到对话结束后往往要过一两分钟记忆才入库异步抽取队列积压严重。查了日志才发现抽取模型调用的是大模型接口但抽取线程没有做并发控制多个长文本排队等待后面的请求全被堵住。解决方法是在 OpenViking 侧配置里把 extractor 的并发数和批处理量分开控制同时给抽取任务增加优先级队列。用户在对话中明确表达偏好时事件会被标记为 high_priority优先进入抽取管道普通闲聊则走低优先级队列。优化后大部分关键记忆能在 3 到 5 秒内写入长期层。4.4 坑三记忆写入风暴导致向量库连接数被打满上线第一天晚间用户量一上来向量库连接数直接打满。根因是每个对话事件都会同步触发抽取抽取完立即写入向量库连接没有复用。后来我在 OpenViking 和向量库之间加了一层缓冲队列并且开启了批量写入模式。记忆记录先在内存中聚合成 batch超过 50 条或者间隔 2 秒再批量写入 Qdrant。这样连接数降到原来的十分之一而且写入吞吐量反而更高。5. Agent 接入代码查询记忆、注入上下文、异步沉淀事件模型和数据层就绪后剩下的是 Agent 和 OpenViking 的集成。下面这套代码是我实际跑通的调用模式。5.1 初始化与基础查询from openviking import OpenVikingClient client OpenVikingClient( endpointhttp://localhost:8080, config_path./openviking.yml ) # 在每轮处理用户请求前调用 def build_context_for_user(user_id: str, task_description: str) - list[dict]: memories client.retrieve( scopefuser_{user_id}, querytask_description, top_k8, # 只检索 active 状态的记忆 memory_statusactive ) return [m.to_context_block() for m in memories]这里要注意 retrieve 的 query 字段我传的是“当前任务描述”不是用户那一句原话。比如用户说“帮我看看上次那个支付问题解决了吗”如果直接拿这句话去查记忆结果会偏向“支付”关键词但匹配不到之前的讨论细节改成任务描述“追踪支付渠道问题的解决进度与相关历史结论”之后检索到的记忆质量明显更好。5.2 把记忆注入到 Agent 的上下文OpenViking 提供了标准记忆渲染格式我通常会把这些记忆块转换成 Markdown 片段拼进 system promptdef render_memories(memory_blocks: list[dict]) - str: lines [## 与该请求相关的长期记忆\n] for idx, mem in enumerate(memory_blocks, 1): lines.append(f{idx}. [{mem[importance]:.2f}] {mem[content]}) if mem.get(constraints): lines.append(f 适用场景: {, .join(mem[constraints])}) return \n.join(lines)这段渲染代码看起来简单实际作用是给大模型提供可理解的记忆上下文同时把重要度数值显式标注出来。我会在 system prompt 里附带一句规则当记忆内容互相冲突时优先采信置信度为 explicit 且时间更新的记录若记忆内容与用户当前说法冲突以当前说法为准并标记该记忆待更新。这个规则的加入极其重要。没有冲突处理规则时模型面对矛盾记忆往往会自行“和稀泥”或选择置信度较低的那条有了规则之后基本不出错。5.3 对话结束后的事件上报每轮对话结束时我把需要沉淀的信息上报给 OpenViking。早期版本我直接上报原始消息后来发现抽取模型会误把系统提示词也抽进去。更稳妥的做法是先让 Agent 自己总结本轮的“值得记忆的事实变化”再把结构化结果发给 OpenVikingfrom openviking import MemoryEvent, EventType event MemoryEvent( event_typeEventType.SEMANTIC_UPDATE, scopefuser_{user_id}, entities[user_1001, report_delivery], content用户确认周报改成企业微信接收不再走邮件, importance0.9, source_agentorder_agent, metadata{turn_id: turn_88231} ) client.emit(event)让 Agent 先自总结再上报有一层额外收益OpenViking 的抽取器会同时拿到原始事件和 Agent 自总结做交叉校验后再写入长期库准确率会提高不少。代价是多一次模型调用但对于需要长期沉淀的场景这点成本非常值得。5.4 记忆异步写入的节奏控制真机实测下来对延迟敏感的操作一定要异步化。我早期试过同步等待事件写入完成再返回结果单个请求耗时增加了 120ms用户体感明显变差。后来改成将事件写入和检索分离读取路径始终走缓存和向量库的同步接口写入路径全部推到后台队列。这样处理用户请求时只需要做一次快速检索不需要关心抽取任务是否已完成。6. 冲突处理与遗忘机制让记忆系统具备修正能力6.1 冲突是长期记忆系统的常态当记忆量达到几千条之后你会发现最要紧的不是“找不到”而是“找到一堆互相矛盾的内容”。用户可能三个月前说过“报表用邮件发”三个月后又改成“用企业微信发”如果你不去处理系统里就会同时存在两条指向不同做法的记忆。OpenViking 的冲突检测机制会在写入新记忆时扫描同一实体范围内是否存在 relation 相反的活跃记录。我使用了一个简单地映射关系描述用户偏好型冲突比如 delivery_channel 从 email 变成了 wecom新记录会将旧记录标记为 superseded而不是物理删除。事实型冲突比如用户之前说“我们数据库 16 个节点”后来更正为“18 个节点”此时应更新实体属性值而不是保留两条平行记录。6.2 用状态机管理记忆生命周期我在每条记忆里设置了四态状态机active - decaying - archived - deleted。active正常参与检索。decaying重要度降到阈值以下或者长期未被访问系统开始降低其检索权重。archived不再参与常规检索但保留在冷存储里可以通过管理后台手动查询。deleted当记忆被确认错误且无保留价值时才真正物理删除。配置里我设置 access_decay_days 为 30 天。一份记忆如果超过 30 天没被访问且重要度低于 0.3就会进入 decaying 状态再过 30 天没被激活就进入 archived。这个机制让系统始终聚焦在用户当前关注点上不会因为历史信息堆积而拖慢检索、干扰判断。6.3 我踩过的冲突处理反例最初我用的是“直接覆盖”策略新的用户偏好进来就把旧记录删掉。后来发现这样太激进用户可能只是场景性偏好比如“在公司时用企业微信在家里用邮件”两条记录应该共存只是适用场景不同。如果盲目覆盖会导致 Agent 在不同场景下表现不一致。后来我把单一 relation 字段改成了完整的“实体 关系 约束场景”结构冲突判定不仅看关系是否相反还要看约束条件是否重叠。只有在约束场景重叠且关系相反时才真正产生覆盖。这个改动解决了大量误覆盖问题。7. 检索质量调优提高记忆召回率的四条经验7.1 检索不能只用一次向量相似度初期版本就是标准流程把任务描述 embedding查向量库 top_k返回相似度最高的记忆。调优后我在检索链路里加入了三个步骤。第一步是粗召回。把任务描述拆成 2 到 3 个不同角度的查询词分别召回一批候选记忆扩大候选池。第二步是精过滤。对召回的记忆做规则过滤状态是否为 active、约束条件是否匹配当前业务场景、是否存在同一条记忆的多版本。第三步是重排。用小模型或简单规则对候选记忆重新打分核心打分维度包括语义相似度、重要度、最近访问时间、来源置信度。重排后的记忆顺序更符合作答需求。7.2 查询改写非常关键调用 OpenViking 的 retrieve 接口时查询文本质量直接决定召回质量。用户说“我那个接口还有问题吗”这里“那个接口”是代词无法直接匹配到具体对象。我会做个前置改写让 Agent 结合当前会话上下文把模糊表述扩写成完整描述再拿改写结果做向量检索。改写之后的典型查询可能是“用户之前反馈过的物流查询接口超时问题是否已解决涉及订单服务或网关服务”。检索效果提升非常明显代价只是多一次 LLM 调用。7.3 实体过滤大于向量相似度很多记忆系统的失效场景不是语义相似度不够而是召回范围没控制好。不同用户的记忆颗粒度、表达习惯差异很大向量相似度很可能把 A 用户的偏好错误匹配到 B 用户头上。OpenViking 的 scope 参数就是干这个用的。我在所有检索入口强制传 scope必要时还要结合实体 ID 做二次过滤。加了这一层之后跨用户记忆串扰的问题基本绝迹。7.4 多样化召回比精确召回更适合任务型场景有段时间我只追检索精确率后来发现任务型 Agent 对记忆的需求和问答类不一样。问答类希望找到“最像的那一条”任务型则希望覆盖当前任务可能涉及的多个侧面比如处理退款时可能需要同时知道用户的支付偏好、上个月的同类工单处理结果、退款流程的注意事项。这几条记忆彼此之间并不相似但都对当前任务有影响。所以我把 top_k 从 5 调到 8并开启 diversity_penalty。实测下来复杂任务的首次解决成功率大约提升了 14%。代价是偶尔会带进来一两句相关性不高的记忆但影响有限。8. 效果评测与最终体验评测一个记忆系统不能只看单点指标。我主要用三组指标衡量它。记忆准确率给 Agent 随机抽取 100 条事实性问题检查它依据长期记忆回答的正确率。这部分主要靠记忆写入质量而不是模型能力。记忆召回率模拟用户提到的历史信息看 Agent 在处理当前任务时能否主动调用相关记忆还是会忽略掉那些“不在当前上下文里但对决策有影响”的信息。这条指标最考验检索链路。记忆污染率主动制造一些会被覆盖的场景然后检查 Agent 是否还会引用已被 superseded 的旧记忆。模拟了 50 个场景早期版本污染率在 20% 以上优化冲突处理逻辑之后降到了 2% 以内。从实际体验看接入 OpenViking 之后最大的变化不是单次回答变聪明了而是随着使用时间拉长Agent 表现得越来越“像同一个助手”。用户上个月说过的偏好能被记住用户更正过的信息能被采纳之前做过的决策在后续任务中被继续遵守。这种一致性带来的信任感是单纯堆模型参数所无法达到的。9. 现阶段我对这套系统的一些保留看法最后聊聊局限。OpenViking 这套架构目前还依赖大模型做抽取和改写因此每一次记忆写入都有模型调用成本。对于日活几十万的 C 端产品来说这个成本必须做分层高频用户走完整抽取流程长尾用户只需要维护基础的用户属性记忆不必全量抽取。另一个问题是记忆抽取的延迟。用户对话结束后需要几秒到十几秒新记忆才能真正沉淀到向量库里。如果你的产品要求“用户刚说完立刻就能在下一句被引用”就需要把记忆读取接口改成先查缓存再查向量库的二级结构而不是等异步任务完成。虽然文章写了这么多细节但我依然认为 OpenViking 的架构思路比工具本身更值得借鉴核心就是记忆分层、结构化记录、冲突处理和生命周期管理。这套思路迁移到任何 Agent 框架上都能有效改善长期一致性问题。我目前正在做的下一步是让 Agent 自己具备“记忆策略调整能力”。比如当它连续多次在某类任务上失败时能主动生成一条过程性记忆提醒自己以后遇到类似任务先检查什么。这相当于把调试经验也沉淀进系统里。按目前的进展来看方向是走得通的等新一轮测试完成后再写一篇展开聊。