如果你用过 Codex 或者 Claude Code大概都有过这种体验上一个会话刚和它确认好项目结构、代码风格、依赖管理方式新开一个终端窗格它又像第一次见面一样问东问西。大家第一反应是“AI 没有记忆那就上向量库”但这两款工具其实各自带着一套轻量的持久化记忆方案而且完全不需要引入向量库。今天就把这两条路线摊开来说清楚从原理到实操从文件配置到踩坑记录。这篇内容适合正在用或准备用 Codex、Claude Code 做日常开发的人尤其是像我这样懒得自己维护一套向量检索服务、又希望 AI 助手能跨会话记住项目背景和约定的人。读完你至少能知道持久化记忆的本质是什么Codex 和 Claude Code 各自用什么机制实现记忆遇到记忆不生效时该从哪里排查。1. Agent记忆体系里到底哪些环节不用向量库1.1 记忆分级短期、长期、永久各指的是什么先把概念理清楚。Agent 的记忆不是一个黑盒而是分层的。短期记忆其实就是单次会话里的上下文窗口模型靠它记住你刚才说的几句话、刚贴的一段代码。长期记忆是跨会话保留的关键信息比如项目背景、环境约定、已经做过的技术决策。永久记忆则是长期记忆里被抽象成规则或者规范的那部分一般写入项目文档变成所有会话都必须遵守的约束。很多人在做 Agent 记忆时第一步就想到把对话历史切块、向量化、存进向量数据库然后每次通过语义相似度检索最相关的片段塞回上下文。这个思路没错但它解决的是“用户对话海量且没有结构”的问题。而在编程场景里真正需要 AI 记住的东西通常是明确、稳定、有结构的比如技术栈清单、目录职责、构建命令、编程风格约束。这些内容放进 Markdown 文件每次会话直接读入效果比任何向量检索都稳定。1.2 向量库方案为什么不是银弹说句得罪人的话在 Agent 编程这个细分场景里向量库经常是杀鸡用牛刀。你要维护一套向量数据库的安装、索引、切分、嵌入模型调用还要处理知识更新后的索引重建复杂度一下子高了一个量级。而且向量检索本质上是“模糊匹配”它返回的是语义相关但未必是你想让 AI 遵守的硬规则。你可以想象你在项目里写死了一条安全规范结果向量检索因为相关度排序问题把这条规范排到了第 20 位之后模型根本没读到后果很严重。另一个问题就是可解释性。文件记忆是白纸黑字的AI 有没有读到、读到了哪几句你打开终端就能看到向量库方案是一个不可直观理解的召回过程出了错你也只能对着调试日志发愁。所以我的观点很明确凡是规则类、结构类的项目记忆优先用文件只有当你有海量非结构化文本、必须做开放式问答或者跨文档语义搜索时再去考虑向量库。2. Codex 的持久化记忆以 AGENTS.md 为核心的路线2.1 Codex CLI 的工作方式与记忆载体Codex CLI 是 OpenAI 推出的终端编程代理它在启动时会主动读取一个名叫AGENTS.md的文件把它作为整个会话的初始上下文。这个文件可以放在你当前项目的根目录也可以放在用户全局目录通常对应~/.codex/AGENTS.md。它的本质是给模型一份“关于这个项目你应该知道什么”的说明书。我习惯把AGENTS.md称作 Codex 的“长期记忆载体”因为只要这个文件存在每次新会话它都会重新读取不需要任何额外的查询逻辑。相比向量库那套流程这种方式的优势是确定性和零依赖。你不需要启动数据库不需要算向量只需要保证文件里的文字是准确、精简、可执行的。Codex 也支持在项目里通过配置开启自动记忆让它在会话结束后把一些重要决定追加到记忆文件里但即使没有这个自动开关手动维护也完全够用。2.2 如何搭建一份可用的 Codex 记忆文件我以自己维护的一个 Python CLI 工具项目为例目录结构大致是my-cli/ ├── AGENTS.md ├── src/ │ └── main.py ├── tests/ │ └── test_main.py ├── pyproject.toml └── docs/ └── architecture.md根目录下的AGENTS.md我写成了这样# AGENTS.md ## 项目概述 - 这是一个命令行工具用于批量处理本地日志文件并输出统计报告。 ## 技术栈 - Python 3.11 - typer 用于命令解析 - rich 用于终端格式化输出 - pytest 用于测试 ## 常用命令 - 运行项目poetry run python -m my_cli - 运行测试poetry run pytest - 构建打包poetry build ## 代码风格 - 所有面向用户的文本必须用英文代码内注释用中文。 - 命令参数命名使用 kebab-case避免使用下划线。 ## 历史决策 - 2025-04-01放弃 argparse改用 typer因为参数校验更严格。 - 2025-04-08日志输出统一走 rich不再使用裸 print。等 Codex 启动并进入这个目录后它会自动把这份内容视为当前项目的基线约束。之后你在会话里让它写新功能它会主动沿用 typer 和 rich不会擅自用 argparse 或者 print也不会把命令写成其他风格。这就是持久化记忆在起作用而且整个过程完全没有向量检索。2.3 Codex 隐藏的“记忆技巧”除了根目录的AGENTS.md有几个细节值得提一下。第一如果项目文档特别大不要把整篇架构设计塞进AGENTS.md它会占用大量上下文窗口导致模型处理代码的空间变小。更聪明的做法是写一句“架构细节请参考docs/architecture.md”并说明在讨论模块划分时应该打开这个文件阅读。Codex 具备主动读取文件的能力它会按需去读。第二Codex 的全局记忆文件和项目记忆文件会合并读取如果你个人对代码风格有统一偏好比如“所有 Python 代码用 TS 风格写类型注解”放进~/.codex/AGENTS.md这样不管你打开哪个项目它都会遵守。要注意的是项目级文件的优先级应该高于全局文件所以别把全局规则写得太死给项目级规则留出覆盖空间。第三养成把会议结论和决策记录追加到AGENTS.md末尾的习惯。比如今天你决定把数据库从 SQLite 换成 PostgreSQL就顺手在“历史决策”加一行。这样哪怕过了一周你重开会话Codex 也不会对着旧代码继续推荐 SQLite。我曾因为偷懒漏写这条结果模型在新会话里一本正经地帮我写了一个 SQLite 的迁移脚本白费半天功夫。3. Claude Code 的持久化记忆CLAUDE.md Skills 体系3.1 CLAUDE.md 的加载层级与优先规则Claude Code 这套路子和 Codex 非常像背靠的都是“文本即记忆”的思想只是文件名换成了CLAUDE.md。它会自动读取用户目录下的全局文件~/.claude/CLAUDE.md以及当前项目根目录下的./CLAUDE.md而且支持在子目录中放置自己的CLAUDE.md让不同模块各自定义上下文。这里有个容易被忽视的点多个CLAUDE.md之间不是简单的“覆盖”关系而是合并注入。比如根目录定义了整体技术栈子目录src/parser/CLAUDE.md里定义了解析器的具体设计约定模型在和该目录相关的代码交互时能同时看到两份内容并根据路径远近判断哪份更相关。这种层级式记忆比单一全局文件要灵活很多适合稍大一点的工程。3.2 用 CLAUDE.md 把项目“调教”成贴心助手我在实际项目里写的CLAUDE.md内容大致如下# CLAUDE.md ## 项目简介 这是一个用于物流仓储场景的库存同步服务基于 FastAPI 开发。 ## 技术约束 - 使用 async SQLAlchemy 2.0 进行数据库操作禁止使用同步会话。 - API 返回结构统一为 { code: 0, data: ... } 格式。 - 所有数据库迁移必须通过 Alembic 生成不允许手动改表结构。 ## 工作流约定 - 需要先写失败测试再实现功能。 - 提交信息必须包含本次修改的关联 issue 编号。 - 运行开发服务器uvicorn app.main:app --reload ## 易错点提醒 - datetime 字段一律使用 timezone-aware 类型禁用 naive datetime。 - Redis 连接池需要显式归还连接防止线程池泄漏。把这段内容写成文件后Claude Code 在大多数情况下的行为都变得“体面”了。它不会再拿 SQLAlchemy 老式 Session 写法糊弄我也不会把 API 返回结构换成别的格式更不会在写测试之前直接给我实现代码。你要知道如果你把这些约定放在对话里临时交代过几句话它就会忘放在记忆文件里它是每次会话的固定输入遗忘的概率就非常低。3.3 Skills 和记忆扩展让记忆变成可执行动作Claude Code 还有一套 Skills 机制本质上是在.claude/skills目录下创建带特定结构的功能包每个 skill 可以包含描述、依赖和一组操作指令。虽然它的初衷是“让模型拥有技能”但在我看来这也是记忆的一种延伸把复杂任务的处理流程固化成模型可调用的模块避免每次会话都从头摸索。比如我建了一个run-release的 skill里面写了发布一个版本需要执行的命令、需要更新的文件、需要检查的注意事项。模型遇到“准备发布 1.3.0”这句话时会主动去加载这个 skill跟着里面记录的步骤执行而不是凭“记忆幻觉”自由发挥。这种记忆不是靠相似度检索出来的而是通过文件名和路径的显式关联在需要时被找到并读取可靠性高得多。4. 两条不用向量库的路线到底怎么选4.1 核心机制对比表对比维度Codex 路线Claude Code 路线备注记忆文件AGENTS.mdCLAUDE.md都是 Markdown 文本加载层级项目根目录 用户全局目录用户目录 项目根目录 子目录Claude Code 层级更细自动记忆部分版本支持自动追加无默认自动写入都鼓励手动维护外部文件引用支持在记忆文件中指明路径让模型读取支持 docs/xxx 语法显式引用可避免上下文膨胀技能固化主要是文档约束支持 Skills 结构化动作Claude Code 更长于流程化适用规模中小型单仓库项目中大型多模块项目按需选择维护难度低一个文件走天下中多文件需注意优先级文件多时需规划对向量库依赖无无本文主题即两条纯文件路线从表格能看到Codex 的路线更“极简”一个AGENTS.md就把记忆这事撑起来了Claude Code 则更像是“文件系统即记忆库”通过多层级文件和多技能包构建了一套更完整的记忆网络。它们的共同点是都不依赖向量库核心逻辑都是“把持久信息写成结构化的文本每次会话直接注入或按需读取”。4.2 从实际场景决定什么时候用文件记忆什么时候用向量库我在线下聊过很多做 Agent 的人大家最大的误区是拿到需求就开始选数据库。其实先要分清楚你的记忆数据长什么样。如果记忆内容是一张张能够用 Markdown 描述的规则表、清单、项目规范那文件方案绝对够用。它的优点是直观、可审查、容易配合版本控制而且不会因嵌入模型升级而突然改变召回结果。如果记忆内容是几万条客服聊天记录、产品说明书、知识文档且需要多轮语义检索才能定位到答案那就得老老实实上向量库。总结成一句话结构化记忆用文件非结构化知识用向量。这不是谁替代谁的问题而是两种不同形态的解决方案。另外还有一点容易被忽略团队协作时候选方案要考虑“共识读取”。AGENTS.md和CLAUDE.md都是纯文本团队成员打开文件就能看到当前所有记忆内容代码评审时也会顺带审一遍而向量库里的索引结果是黑盒团队很难确认模型到底记住了哪些知识。如果你们公司有严格的知识溯源要求文件路线明显更安全。4.3 混合路线文件记忆为主向量库按需补充别把文件记忆和向量库理解成对立的两极更好的做法是分层设计。主记忆层放项目规范和团队公约用文件搞定如果项目里确实积累了大量 FAQ、往期设计文档可以为它们单独建一个向量索引在对话涉及这些内容时通过工具调用做检索。Codex 和 Claude Code 都支持自定义工具和命令这给了混合方案很大的自由度。我个人经验是一个项目里90% 的记忆最后都会沉淀成若干条清晰规则只有剩下 10% 是模糊的、需要语义匹配的“知识”。与其为了那 10% 引入一整套向量基础设施不如先用文件记忆把 90% 做好这带来的即时收益大得多。5. 实操实录在同一个项目里配置两套持久化记忆5.1 准备一个示例项目为了验证两条路线的真实效果我把同一个练习项目分别交给 Codex 和 Claude Code 跑了一遍。项目是一个负责发送邮件通知的服务代码量不大但存在一些独特的约定邮件正文必须用 HTML 模板渲染、每次发送必须写入审计日志、测试环境不能真实发信。这三条约定就是我想让 AI 跨会话记住的核心内容。我在项目里预先放了两种记忆文件mail-service/ ├── AGENTS.md // 给 Codex 用 ├── CLAUDE.md // 给 Claude Code 用 ├── src/ │ ├── notify.py │ └── templates.py ├── tests/ │ └── test_notify.py └── pyproject.toml两个文件开头都是简明的项目说明把“邮件模板渲染、审计日志、禁止真实发信”三条规则分别写了进去。这样能尽可能公平地观察两个工具在同样基线条件下的表现。5.2 配置 Codex 记忆并验证我先用 Codex 打开这个目录新建了一个会话直接提需求“帮我加一个支持批量发送邮件的函数记得遵守项目约定。”Codex 根据AGENTS.md里的内容在实现时自动使用了项目中已有的render_template函数而不是内联拼接 HTML它在发送逻辑前加了一个write_audit_log的调用最后它还很“懂事”地补充了一句“测试时记得把 SMTP 客户端替换成 mock”。这三条表现正好对应记忆文件里的三条核心约定。为了更明显一点我还在会话里故意用一个违反约定的说法试探“直接用 SMTP 库发不管审计日志行不行”Codex 几乎立刻拒绝了并指出项目约定里明确要求写审计日志。这说明记忆不只是“长期”也是有一定约束力的。当然如果你的规则写得太模糊或者埋没在大段散文里模型依然可能踩线所以记忆文件的表达要尽量像“代码规范列表”那样指令化。5.3 配置 Claude Code 记忆并验证在同一个目录我换成 Claude Code 进行操作。我先问了一个“如何测试发送功能”的问题Claude Code 读取CLAUDE.md后给出了使用 mock SMTP 和 fake 收件地址的测试方案并主动提到“测试环境不能真实发信”。随后我要求它添加 HTML 模板支持它直接从项目 templates 目录里找出了已有的模板文件没有另起炉灶。整个交互过程非常顺很像一个对项目已经有充分了解的协作者。Claude Code 还有个优点是它会不止一次地展示“它知道自己在遵循什么”。在操作日志里你会看到类似“根据项目约定使用 AST 生成 HTML 模板”这样的说明这对你检查记忆是否生效很有帮助。对比下来两者都能达到持久化记忆的目的只是 Claude Code 在对话中的解释更主动Codex 则更倾向于在代码里体现约束。5.4 两条路线的现场对比与调整心得实际跑下来我更清楚地意识到这两条路线解决的其实是同一个问题但面向的使用习惯不同。Codex 的AGENTS.md更像一份“团队公约”适合你希望 AI 严格按显式规则执行Claude Code 的CLAUDE.md更像一份“项目入坑指南”适合希望 AI 能主动理解上下文、并在多模块间灵活跳转的场景。唯一让我觉得需要调整的地方是记忆文件的内容长度。第一次我写得比较啰嗦塞了两大段背景介绍结果两个工具的输入 token 都被占掉不少真正对编码有用的规则反而变得不突出。后来我把背景压缩成三行把规则条目化两边都明显更听话。这也算一个很重要的经验持久化记忆不是写得越多越好而是要写得“可执行”。6. 常见问题与排查技巧6.1 记忆文件为什么不生效先说最常遇到的问题明明建了AGENTS.md或CLAUDE.mdAI 却一副没见过它的样子。优先检查文件名和位置是否完全正确。Codex 默认找的是AGENTS.md文件名不能写成agents.md或者AGENT.mdClaude Code 默认找的是CLAUDE.md别写成Claude.md。大小写和拼写错误是重灾区。然后检查你启动 CLI 的工作目录是否是项目根目录。如果你在src/子目录里启动会话Codex 和 Claude Code 可能只在当前目录向上寻找记忆文件找不到根目录的配置。我的习惯是固定从仓库根部启动工具并且把记忆文件纳入版本控制这样任何新机器拉下来都能自动生效。还有权限和编码问题。在 Linux 或 macOS 上如果记忆文件权限过高或者编码不是 UTF-8某些版本的工具会读取失败。你可以用file命令确认文件编码。如果你用的是 Windows 桌面版还要注意换行符最好统一成 LF避免终端解析异常。6.2 记忆内容太多把上下文撑爆怎么办有人会一开始就在记忆文件里放几千行说明文档结果每次会话都超长模型还没开始写代码就先被记忆淹死了。解决方法是把“常驻记忆”和“按需记忆”分开。AGENTS.md和CLAUDE.md里只保留那些做任何代码改动都必须知道的规则、命令、约束大块的架构说明、设计稿、会议纪要这类低频信息用“文件引用”的方式来管理。Codex 那边你可以在记忆文件里写“详细设计文档在docs/design.md当需要修改模块边界时先读取该文件”Claude Code 那边可以直接用docs/design.md语法引用让模型在需要时才去打开。这样一来每次会话的常驻上下文保持精简深入到具体模块时再补充加载大文件既不撑爆窗口也不丢失记忆。6.3 记忆过时和冲突怎么维护记忆文件最怕的是“旧规则还在新代码已经用不上了”。如果你发现 AI 还在按照几个月前废弃的规范写代码多半是文件里还在写那条规范。我给自己定了一个机制每次有一次比较大的技术决策变更就在记忆文件里加一行“历史决策”并明确标出“已弃用”的字样同时更新当前规则。例如## 历史决策 - 2025-03-01使用 pip requirements.txt 管理依赖已弃用改用 poetry。 - 2025-06-01统一使用 poetry 管理依赖。冲突问题更多出现在存在全局记忆和项目记忆的场合。假设你个人全局全局文件写了“优先使用 SQLAlchemy”而项目文件规定“用 drizzle ORM”两个文件合并后模型可能无所适从。解决办法是给项目记忆一个显式的覆盖声明比如在CLAUDE.md第一行写“本项目所有依赖管理规则以本文件为准忽略全局规则中的相关条目”。给规则加优先级能避免很多隐性冲突。6.4 遇到“记忆丢失”先做这三件事如果你明显觉得这次会话里 AI 没有遵守记忆别急着怪工具按顺序排一下。第一确认当前终端目录和我们配置记忆的目录是不是同一个第二直接问模型“请你列出当前项目的所有约定”看它能否准确说出几条这能快速判断记忆到底有没有被加载第三看操作日志中是否出现读取记忆文件的行Codex 和 Claude Code 都会在调试模式下打印读取了哪些上下文文件。看完这篇文章你会发现持久化记忆并没有想象中那么高不可攀。两条路线看起来只是两个文件名之间的差别底层却是同一套“以结构化文本替代语义检索”的思路。我自己实际用了一个月下来最大的体感是当你不再依赖一个庞大的向量基础设施时维护记忆的门槛会低到让人忘记它的存在你只需要像写文档一样去写记忆文件AI 就会像一个真正懂你的老搭档一样稳定发挥。最后再分享一个小建议把记忆文件写得像一封给未来同事的交接信多写“为什么”少写“感觉”你的 Agent 会比其他人都更靠谱。