用 Codex 的时间越长我对它最大的意见反而不是代码质量而是它几乎没有长期记忆。上午刚告诉它这个项目用 pnpm 管理依赖、组件库用的是内部封装、测试必须过 lint 才能提交下午新开一个会话它又把同样的问题问一遍。OpenViking 就是冲着这个痛点来的它是一个给 Codex 加长期记忆的开源方案核心思路是在 Codex 外层套一个“记忆层”让编程 agent 从“每次会话都失忆”变成“该记住的全记住”。这篇文章我会从记忆机制的拆解、OpenViking 的设计思路到安装接入、常见报错排查把完整实践记录写下来。适合所有被 Codex 反复失忆折磨的开发者也适合想搞懂 agent 记忆体系到底怎么落地的人。1. 先搞清楚 Codex 为什么“记不住事”1.1 无状态会话是 Codex 的架构选择不是 bug先别急着骂 Codex 笨。它记不住事根本原因是底层架构就是无状态的。每一次请求都带着完整的上下文发给模型模型算完就返回结果服务端不会在你的会话之间保留任何“项目记忆”。这个设计在工程上非常合理服务端无状态意味着好扩容、好调度、单次请求失败不影响其他请求整个系统的复杂度会低很多。但问题也随之而来。开发者实际用起来会有一种很拧巴的感觉Codex 在单个会话里表现得像经验丰富的老手——给它一个任务它能自己读文件、跑测试、改代码可一旦你关掉会话重开它就彻底失忆了。你之前跟它确认过的技术选型、目录约定、代码风格全都要从头再讲一遍。我自己的体会是这种“失忆”在小型 demo 项目里还能忍但到了真实业务项目里每个新会话都需要花几百个 token 把项目背景重新灌给它而且它还会因为缺少历史决策给出和上次完全相反的方案。比如上周它刚跟你说好“不要用 uuid 做主键统一用雪花 ID”这周新会话里又给你写了个 uuid 生成器。这不是模型能力的问题是缺少“回忆入口”的问题。人写代码靠大脑里的长期记忆而 Codex 每次开会话都等于换了一个全新的脑子。1.2 短期记忆、长期记忆、永久记忆这三层到底怎么分要理解 OpenViking 做了什么先得把 agent 记忆体系里的三组概念理清楚。现在网上讨论 agent 记忆经常把短期、长期、永久混在一起说但实际上它们解决的问题完全不同。记忆层次生命周期典型载体Codex 原生状态典型痛点短期记忆单次会话内上下文窗口、会话历史文件自带窗口长度有限超长任务会截断长期记忆项目生命周期项目记忆库、约定文件、文档基本没有跨会话全忘反复交代背景永久记忆开发者的长期偏好全局配置、个人偏好文件只有少量 settings风格偏好无法跨项目迁移短期记忆好理解就是当前对话里模型能“看见”的所有内容。Codex 的上下文窗口就是它的短期记忆窗口多大它短时间内就能记住多少窗口一滚动前面的内容就丢了。很多人在长任务里遇到 Codex“前面改过的东西后面忘了”本质就是短期记忆超载。长期记忆要解决的是“跨会话但限项目”的问题。比如这个项目用 pnpm 还是 npm、测试框架是 Vitest 还是 Jest、提交信息需不需要带 issue 号这些在一个项目周期内是稳定的。它们不应该每次开会话都重新交代但 Codex 目前没有原生机制去维护这种信息。永久记忆则是更上层的开发者偏好比如“我喜欢函数式风格”“错误处理统一用 Result 而不是 try/catch”“注释要写中文”这类信息应该跨项目生效。Codex 的 AGENTS.md 或自定义指令能承担一部分职责但它更偏向“静态说明书”缺少从实际会话中持续沉淀的能力。OpenViking 的定位就是补上长期和永久这两层。它不干预单次会话里的短期记忆那是 Codex 自己的事它专注于把会话中产生的、值得跨会话保留的信息结构化地存下来并在合适的时候重新注入。1.3 OpenViking 不是聊天记录备份而是一个“记忆工作流”我最早听说 OpenViking 这个名字时以为它就是把 Codex 的会话日志存下来方便搜索。真正看它的设计之后才发现思路完全不一样它不存对话只存“从对话里提炼出来的记忆条目”。聊天记录是流水账里面 90% 是噪音。真正的项目记忆应该是高度精炼的结论和约定比如“后端接口统一走 /api/v1 前缀”“新增依赖必须走 pnpm approve-builds”。OpenViking 做的事情就是在 Codex 会话结束后用模型把这次会话里值得沉淀的信息抽取出来格式化成结构化条目存进记忆库下次开会话前再根据当前任务把相关条目取出来注入给 Codex。它本质上是一个记忆工作流提取 —— 结构化 —— 去重合并 —— 按需召回 —— 注入上下文。每一环都可以单独配置和微调。理解了这套流程后面所有的配置项和实操都顺理成章了。2. OpenViking 的核心设计记忆条目、提取机制和注入策略2.1 记忆的最小单位是“条目”不是段落OpenViking 存储记忆的最小单位是条目entry每条记忆对应一个独立的事实、约定或决策。我实际打开过它的存储文件每条记录包含如下字段{ id: mem_20241123_b2f1, type: project_convention, content: 项目使用 pnpm workspace新包必须放在 packages/ 目录下, tags: [pnpm, monorepo, structure], source: session_20241123_001, confidence: 0.9, created_at: 2024-11-23T10:12:00Z, updated_at: 2024-11-23T10:12:00Z }type 字段用来区分记忆类型常见的有 project_convention项目约定、tech_decision技术决策、workflow操作流程、error_record踩坑记录、user_preference用户偏好等。这个分类不是摆设它直接决定后续检索和注入时的优先级权重。为什么不用“段落”做单位因为段落信息密度太低。如果把整个会话总结成一大段文字存下来召回的时候你没有办法精确判断哪几句是当前任务需要的只能整段注入token 消耗大且容易带入不相关的内容。条目化之后每条记忆控制在 20~80 个 token 左右注入的时候按需组合效率完全不同。我刚用 OpenViking 的时候犯过一个错一条记忆写了一大段恨不得把当时讨论的前因后果全塞进去。后来发现这种长条目召回率反而低因为检索排序时关键词匹配度被稀释了。好的记忆条目应该像便利贴一句话能说清的事绝不写两句话。2.2 记忆提取什么该记什么不该记谁来决定记忆提取是 OpenViking 里最核心也最需要调优的一环。它在每次会话结束后执行一个 sweep 流程让模型阅读整个会话从中抽取“值得跨会话保留的信息”然后写入记忆库。什么算“值得保留”这里面有很强的经验判断。以我自己的项目为例值得记的通常是三类第一类是明确的项目约定比如“部署流程是先跑 test再 build最后发版”第二类是反复出现的修正比如“Codex 两次都误用了旧的 API 签名应该提醒它查阅当前版本文档”第三类是用户的明确偏好比如“用户要求所有错误提示文案改用人话不要抛原始异常”。不值得记的也很多见会话中临时计算出来的中间数据、一次性的调试命令、随口讨论但没有结论的内容这些写了只会污染记忆库。OpenViking 默认用规则触发 模型判断结合的方式做提取。规则上它会优先关注包含“以后”“记住”“不要”“改用”“统一”这类关键词的句子再辅以模型对整个会话的语义判断筛掉那些“看起来像结论但其实是随口一说”的内容。sweep 还有一个关键步骤是去重与冲突处理。同一个项目跑了几十次会话关于“构建命令是什么”的记忆可能被反复写入。OpenViking 会按 content 的语义相似度合并重复条目更新 updated_at 时间戳。如果新旧记忆冲突——比如旧条目说“用 Yarn”新条目说“用 pnpm”它会以后写入的为准但不会默默删掉旧记录而是把旧的标记为 superseded方便以后审计。2.3 记忆召回与注入在合适的时机把合适的记忆塞给 Codex存了记忆不用等于白存。OpenViking 的注入策略我理解下来其实是三个问题什么时候注入、注入哪些、注入多少。时机上最基础的是会话启动时注入相当于给 Codex 一份“项目须知”把项目级和全局级的关键记忆一次性塞给它。但只做会话启动注入还不够因为真实任务往往是动态变化的。比如你让 Codex 改一个支付模块的代码它真正需要的是和支付模块相关的记忆而不是整个项目的全部约定。所以 OpenViking 支持在任务进行中按需注入你可以把当前任务描述拆成关键词动态召回相关的记忆条目。检索排序的逻辑不复杂实际实现里通常是三个因素的加权关键词相关度、更新时间、置信度。相关度高的优先近期更新的优先之前验证过可信的优先。这个排序算法远不需要做到 RAG 那么多花活因为记忆库的量级通常也就几百上千条线性扫描加简单打分完全够用。注入量必须克制。OpenViking 有一个 max_inject_tokens 配置默认我设的是 1200。这个数字不是随便拍的它算的是上下文预算Codex 每次任务的可用 token 是固定的任务描述、代码上下文、工具输出会占掉大头记忆注入只能占其中一小块。如果一次注入几千 token 的记忆记忆是够了但 Codex 真正处理任务的空间就少了表现反而变差。注入位置也有讲究。全局性的记忆比如开发者偏好适合放在 system prompt 层面相当于给模型设定身份项目级记忆则更适合放在用户消息开头跟着当前任务一起进来。我自己测试下来混在一起注入的效果没有分层注入好。OpenViking 在实现里做了简单的分层全局记忆进 system项目记忆跟任务描述拼接。2.4 存储设计为什么用一个目录和几个 JSONL 文件就够了OpenViking 的存储方案朴素得让很多人意外项目根目录下建一个 .viking 目录里面放几个 JSONL 文件仅此而已。它没有用任何数据库没有独立的服务端进程。.viking/ ├── project.jsonl # 项目级长期记忆 ├── global.jsonl # 开发者级永久记忆 ├── meta.json # 记忆库元信息 └── lock.json # 并发写入锁这个设计我认为是刻意的。文件即数据库的最大好处是git 友好。记忆库可以跟着代码仓库一起提交每次记忆变化都能在 review 时看到 diff想回滚就回滚团队协作时每个人拉下来就是同一套记忆。相比之下如果用数据库记忆库就变成了一个独立于代码仓库的“黑盒”团队里新成员 clone 项目时还要额外去同步一份数据库工程体验会差很多。JSONL 格式则是考虑了追加写入的便利性。每行一个 JSON 对象sweep 产生的新记忆直接 append 到文件末尾不需要像 JSON 数组那样整体重写整个文件也不用像 SQLite 那样考虑 schema 迁移。数据量小的时候这种看起来“原始”的方案反而是最稳的。不过文件方案也有代价。最大的问题是并发写入冲突如果你同时开了两个 Codex 会话两个 sweep 同时写同一个文件可能会互相覆盖。OpenViking 用了一个简单的文件锁来规避实际体验下来基本没出过问题。3. 实操把 OpenViking 接入你的 Codex 工作流3.1 安装和初始化十分钟内跑通OpenViking 的安装没有太多要说的Python 生态的标准操作。建议用虚拟环境装避免污染系统 Pythonpip install openviking如果你喜欢跑源码也可以直接 clone 仓库然后手动装依赖。源码安装的好处是你随时可以改提取规则和注入逻辑对喜欢折腾的开发者来说更友好。我个人的建议是先用 pip 装稳定版跑通流程确认这套模式对你有用之后再去读源码改细节。装完之后在项目目录里初始化cd your-project openviking init初始化会做三件事创建 .viking 目录、生成默认配置文件 .openviking.toml、扫描当前项目结构生成几条基础的种子记忆。种子记忆一般包括项目语言、包管理器、构建命令这些一眼就能从配置文件里看出来的信息用处不大但能让你立刻看到记忆库长什么样。3.2 关键配置项逐一解读配置文件是 TOML 格式我贴一份我实际在用的配置加上了注释说明# .openviking.toml [memory] store_dir .viking # 记忆库目录 max_inject_tokens 1200 # 单次注入的最大 token 数 auto_sweep true # 会话结束后自动执行记忆提取 min_confidence 0.35 # 低于该置信度的记忆条目不写入 dedupe_threshold 0.85 # 语义相似度高于该值时判定为重复 [retrieval] top_k 8 # 每次召回的候选记忆条数 recency_weight 0.3 # 更新时间在排序中的权重 relevance_weight 0.5 # 关键词相关度权重 confidence_weight 0.2 # 置信度权重 [inject] show_in_system true # 全局记忆注入 system prompt project_prefix 项目约定 # 项目记忆的前缀文案max_inject_tokens 是我最常调的一个值。项目越复杂需要注入的约定越多但这个值不能无脑调大。按我的经验Codex 的上下文窗口就算有 200k任务本身的输入输出也会吃很多 token记忆注入超过 1500 之后收益就开始递减了。1200 是一个保平安的值。min_confidence 和 dedupe_threshold 是控制记忆质量的。提取模型对某条信息的把握度低于 min_confidence 时直接丢弃宁缺毋滥dedupe_threshold 则是为了避免同一个事实被重复存成多条。这两个参数建议先保持默认跑一段时间看到实际效果后再调。3.3 三种接法脚本包装、手动双命令、编辑器内集成OpenViking 接入 Codex 没有官方插件因为它本质上不是 Codex 的功能扩展而是工作流辅助工具。我自己用过三种接法各有利弊。最推荐的是脚本包装。写一个 wrapper 脚本在 Codex 启动前自动注入记忆在会话结束后自动执行 sweep#!/usr/bin/env bash # ~/.local/bin/codex-mem set -euo pipefail PROJECT_DIR${1:-$(pwd)} # 会话启动前把相关记忆注入环境变量 export OPENVIKING_INJECTED_MEMORY$(openviking inject --project-dir $PROJECT_DIR --task ${2:-}) # 启动真正的 Codex CLI把剩余参数透传 command codex ${:2} # 会话结束后执行记忆提取并追加写入记忆库 openviking sweep --project-dir $PROJECT_DIR --session $(mktemp)这里有个关键细节注入是通过环境变量传给 Codex 的。为什么会话代码里能读到这个变量因为 OpenViking 注入的内容最终是要进上下文。如果你用的是 Codex CLI可以配合它的自定义指令机制在配置里让模型启动时优先读取这个环境变量的内容作为项目背景补充。第二种接法是手动双命令不搞任何包装。开会话前先手动跑一次openviking inject把输出复制到对话里会话快结束时手动跑openviking sweep把本次会话总结沉淀下来。这种方式胜在透明可控但依赖你的习惯很容易忘了跑。第三种接法是编辑器集成主要是 VSCode 里的 Codex 插件。插件版的 Codex 走的是同一套 CLI 内核所以脚本包装的方式理论上也能生效但插件有自己的进程管理方式环境变量传递不一定可靠。我的建议是如果你主要在 VSCode 里用 Codex初期先用“手动双命令”的方式验证价值等确定这套流程对你有用再考虑把 wrapper 脚本嫁接到插件的自定义命令里。3.4 一次完整的记忆写入与召回演示我拿一个实际项目演示假设项目是 monorepo使用 pnpm workspace后端用 Fastify前端用 React。第一次会话我给 Codex 的任务是“修复登录接口偶发 500 错误”。在会话过程中我明确说了一句“以后后端新增接口都要按我们约定的错误码规范统一用 BIZ_ 前缀”。这句话是关键约定OpenViking 的 sweep 在会话结束后会把它抽取出来。执行 sweep 之后打开 project.jsonl 会看到类似这样的记录{id: mem_20241123_b2f2, type: project_convention, content: 后端所有业务错误码统一使用 BIZ_ 前缀禁止直接返回内部异常信息, tags: [backend, error-code, api], source: session_20241123_002, confidence: 0.92, created_at: 2024-11-23T18:30:00Z, updated_at: 2024-11-23T18:30:00Z}第二次新开会话我给 Codex 的任务是“给用户模块加一个查询接口”。OpenViking 召回时会匹配到 tags 里的“backend”“api”把这条记忆捞出来拼接成一段项目背景注入进去。Codex 在生成接口代码时就会自觉带上 BIZ_ 前缀的错误码体系不再需要你重新交代一遍。这一步是整个方案的收益点你只说过一次的约定从此之后每次都能被记住而且是精准记住不是把一大坨聊天记录扔给它让它自己猜。4. 常见问题与排查实录接入过程中踩过不少坑我把最典型的几个问题整理成速查表每一个都是实际遇到过的。4.1 “model is not supported”报错模型名可能根本不存在Codex 接入第三方模型服务时最容易碰到这类报错。表现形式是请求发出去服务端直接拒绝提示你配置的模型名不被支持。我印象很深的一次同事配置 Codex 指向团队的内部网关配置文件里写了一个模型名看起来很像官方某个版本但实际上那个名字在网关后端根本不存在可能是网上某个旧教程里的写法。排查顺序很简单先确认 Codex 配置文件里的模型名和实际服务提供方支持列表是否一致然后确认账号或 Key 是否有该模型的访问权限最后确认 base_url 是否指向了正确的服务地址。这类报错和 OpenViking 本身没有关系但如果你用了记忆注入会多一层疑惑因为配置里 OpenViking 也涉及模型调用sweep 需要模型做提取你会搞不清是哪个环节报错。我的排查办法是先临时关掉 OpenViking只跑 Codex 确认模型连通性再开回来测记忆链路。4.2 本地转发组件连不上先确认服务本身在跑很多开发者会把 Codex 接入统一的本地请求转发服务用来做日志审计或者统一 Key 管理。这类场景下Codex 请求一个 /responses 端点时经常会出现“本地服务连接失败”之类的报错后面还跟着一堆看起来很像网络问题的英文细节。我的经验是见到这种报错先把锅从 Codex 身上拿开因为大概率是转发服务本身没起来或者参数不对。先确认监听端口有没有在跑用 curl 直接打一下本地端点看返回是否正常再检查 Codex 的 base_url 是否指向了正确的端口和路径最后检查鉴权头是否传了很多转发组件对请求头校验很严格缺失必要头时不会返回友好错误而是直接连接断开。另外有个冷门但很坑的点如果你的转发服务是 HTTPS 端点用的是自签证书Codex 在握手阶段就会失败。解决办法是把自签证书加到系统信任区或者让转发服务走 HTTP 回环地址省掉证书链的问题。4.3 “auth token is unavailable”登录态和 Key 是两回事这个报错最常见的场景有两种。一种是使用 ChatGPT 账号登录的模式本地 token 过期或没登录Codex 找不到有效的认证凭据。另一种是使用第三方 API Key 的模式Key 没写对或者根本没写进配置。两种场景的修法完全不同所以排查的第一步是搞清楚你现在用的是哪种认证方式。ChatGPT 账号模式重新登录一次就好第三方 Key 模式检查配置文件里的 Key 是否带上了正确的前缀、有没有多余空格、环境变量有没有被正确加载。我自己的习惯是把 Key 放在环境变量里不在配置文件里存明文这样干净一些。如果你发现 Codex 偶尔报 token 不可用、偶尔又能用大概率是环境变量在某个子进程里没有传递过去这属于 shell 环境问题和 OpenViking 无关。4.4 “unrecognized configuration setting”十有八九是版本不一致Codex 升级之后我遇到过几次“存在无法识别的配置项”的警告。Codex 的做法是忽略未知配置继续运行但如果未知项太多你就要警惕是不是参考了过时的配置教程。排查思路就一条先codex --version确定当前版本再去官方文档里对照当前版本支持的配置项。有些配置项改了名比如从 camelCase 改成 kebab-case有些则整个废弃了。我的建议是每次 Codex 大版本升级后都花十分钟 review 一遍本地配置把过时项清理掉。如果你同时用了 OpenViking 的注入逻辑注意不要把 OpenViking 的配置项写进 Codex 的配置文件里它们俩的配置体系是独立的写错位置虽然不会崩但会造成排查混乱。4.5 OpenViking 自身的问题记忆污染和上下文膨胀OpenViking 跑久了最大的问题是记忆库慢慢变得臃肿注入的内容越来越多Codex 的注意力被分散反而出现“明明记忆里有正确约定但模型视而不见”的情况。我的处理方法是定期做记忆清理。OpenViking 提供了手动审查命令可以把置信度低、更新时间久、或者标记为 superseded 的条目批量清理。更实用的做法是配合 git整个 .viking 目录都在仓库里你可以在每次较大的需求迭代后翻一下 project.jsonl 的 diff把过时条目像清理技术债一样清理掉。还有一个要注意的是“记忆污染”有时候会话里只是随口说的一句玩笑话或者临时假设sweep 模型误判为重点约定写进了记忆库。这种污染条目比没有记忆更可怕因为 Codex 会把错误约束当成事实遵守。我遇到过一次记忆里混进了一条“当前分支就是生产环境”的错误约定导致 Codex 在生成部署相关代码时全部按生产环境参数来处理。从那以后我养成了一个习惯每次重要会话结束后扫一眼新增的记忆条目确认没有脏数据再继续。5. 使用心得与避坑建议5.1 记忆条目怎么写召回效果才能好写记忆条目是一门被低估的手艺。同样是记录一条错误处理约定“后端错误码要规范”这种写法召回效果就很差因为通用词太多检索时匹配不精确。“后端接口错误码使用 BIZ_ 前缀”这样带具体标识的写法后续任务提及时很容易被关键词命中。我总结了一个简单的写法模板主体动作 具体对象 限定条件。比如好“新增后端接口时必须按 BIZ_ 前缀定义业务错误码”不好“错误码要有规矩”“后端规范要好”另外条目里尽量带上“禁止”“必须”“统一”这类强约束词不是为了吓人而是这类词在任务描述里出现时和记忆条目的语义匹配度更高。从纯工程角度看这就是提高召回精度的实用技巧。5.2 自动提取 手动补充双轨并行最稳不要完全依赖自动提取。sweep 的模型判断再强也有抓不住重点的时候。我的工作流是平时让 auto_sweep 自动跑但我手里始终会手动往记忆库写关键条目。手动补充的入口非常简单类似 git 的提交式体验。每次完成一个重要技术决策或者和 Codex 纠偏了一次方向性错误我都会顺手手动加一条openviking add --type tech_decision \ --content 用户模块查询接口全部走只读从库禁止直连主库 \ --tags db,replica,user-module这种双轨制的核心逻辑是自动提取负责量大面广的覆盖手动补充负责精准投放。特别是在项目刚启动、约定正在形成的那两周手动补充的密度应该最高等记忆库稳定下来之后再慢慢交给自动提取。5.3 不要往记忆里塞密钥和敏感配置这是红线不是建议。OpenViking 的记忆库通常跟着代码仓库走如果你把数据库密码、API Key、内部域名塞进记忆条目等于把凭据明文提交到仓库里任何一个能读到仓库的人都能直接看到。有些人会觉得“我的仓库是私有的没关系”但代码仓库的访问权限往往比你想的更宽CI 机器能读、部分外包人员能读、半年后你自己可能都忘了里面有什么。万一仓库后续被分享出去凭据就直接裸奔了。我在实际使用中给 OpenViking 加了一条经验规则凡是包含密钥、Token、密码、内网地址的记忆条目一律不写而是写“数据库连接信息见 .env 文件不要硬编码”。5.4 团队协作时把记忆库当成代码的一部分来维护OpenViking 的文件存储设计天然适合团队协作。我把 .viking 目录随代码仓库一起提交约定每个成员在提交代码时如果涉及记忆变更一并提交。团队协作里最需要把控的是记忆冲突。两个成员在各自分支上往记忆库里写入了冲突的约定merge 时 JSONL 文件会像普通代码一样产生冲突解决方案也和普通代码一样手动保留正确的一方废弃另一方。这个流程看起来繁琐但实际上逼着团队在“什么才是项目正确约定”上达成一致反而是件好事。我强烈建议把“Review 记忆变更”加进代码审查流程里。每次 PR 除了看代码 diff顺手看一眼 .viking 目录的 diff重点关注有没有错误记录混进去。这个习惯坚持下来记忆库的质量会明显比个人项目高出一大截。5.5 记忆不是靠堆数量而是靠稳定性和可信度用了一段 OpenViking 之后我最大的体会是不要太关注记忆条目数量要关注条目被验证的次数。一条“构建命令是 pnpm build”的记忆如果几次会话里 Codex 按它执行都成功了它的可信度就在提升如果哪次 Codex 按记忆操作失败了说明记忆已过时要及时修正。OpenViking 的 confidence 字段本质上就是干这个的。每次 Codex 按某条记忆执行任务后OpenViking 可以根据任务结果给该条目做正向或负向反馈。虽然默认配置里这个反馈回路比较粗但方向是对的。我自己会在每周复盘时专门看那些被标记为低置信度或者长期未被召回的条目该删就删该改就改。一套记忆体系好不好用不在于存了多少而在于用的那一刻拿出来的东西准不准。
