1. 为什么 Agent 的记忆问题值得单独拿出来聊做 Agent 开发的人绕不开一个尴尬的现实模型本身是无状态的。你这一轮跟它聊得再深入下一轮开个新会话它对你一无所知。这不是模型能力问题而是架构决定的——每次推理都是一次独立的函数调用上下文窗口里有什么它就知道什么。于是持久化记忆成了 Agent 从玩具走向生产工具的分水岭。一个只会单轮问答的 Agent 是 demo一个能记住你上周提过的偏好、记得三天前那个未完成任务的 Agent才勉强算得上助手。市面上讲 Agent 记忆的方案十篇里有八篇会把你引向向量数据库把对话切片、embedding、存进 Pinecone 或 Milvus、检索时做相似度召回。这套 RAG 思路确实成熟但它有个隐性成本——你得维护一整套检索基础设施embedding 模型要选型切片策略要调召回质量要评估还得处理检索出来的东西其实不相关这种经典翻车场景。而 Codex 和 Claude Code 这两条路线走的是另一条路不依赖向量库用文件系统和结构化文本做记忆载体。这个选择乍看土但背后有非常清醒的工程判断。我前后在两个项目里分别用过这两套机制踩过一些坑也总结出一些文档里不会写的经验。这篇就把两条路线的设计逻辑、实操细节和适用边界掰开讲清楚。先说结论性的判断方便你对号入座如果你做的是个人开发者工具、CLI 助手、代码库级别的长期协作文件式记忆的性价比远高于向量库如果你做的是面向海量用户、跨会话跨设备的通用助手那向量库或混合方案仍然更合适两者不是替代关系而是不同规模、不同场景下的取舍。下面进入正题。2. 两条路线的底层分歧记忆到底存在哪里要理解 Codex 和 Claude Code 的记忆设计得先搞清楚一个根本问题记忆的存储介质决定了它的检索方式和能力边界。2.1 向量库路线的隐含假设向量库方案的核心假设是记忆条目太多多到无法全部塞进上下文所以必须靠相似度检索来挑出相关的几条。这个假设在什么情况下成立当你的记忆规模达到几千上万条、且条目之间高度异构时它成立。但反过来如果你的记忆总量只有几十条、几百条全部读进上下文完全可行那向量检索带来的收益就非常有限反而引入了 embedding 成本、召回误差和基础设施复杂度。我见过不少团队项目刚起步就上了向量库结果发现召回出来的内容经常驴唇不对马嘴最后还得加一层 rerank再不行就人工规则兜底。这套东西的维护成本远超它解决的问题。2.2 文件式记忆的核心逻辑Codex 和 Claude Code 的共同点是把记忆写成人类可读的文件放在项目目录或用户配置目录里需要时直接读取。这带来几个直接好处可审计你打开文件就能看到 Agent 记住了什么不用去数据库里查可编辑记错了直接改文件不用重新 embedding可版本控制记忆文件能进 Git跟着代码一起演进零基础设施不需要额外部署任何服务。代价也很明显记忆规模受限于上下文窗口。文件太大就读不进来所以必须做摘要、分层和裁剪。这就是两条路线真正开始分道扬镳的地方——它们对如何组织这些文件给出了不同的答案。2.3 一张表看清分歧点维度向量库路线Codex 文件路线Claude Code 文件路线存储介质向量数据库项目内 Markdown 文件项目/用户级 Markdown 文件检索方式相似度召回全量读取 层级组织全量读取 显式引用记忆写入自动切片入库显式指令写入显式指令 自动摘要可审计性低需查库高直接看文件高直接看文件规模上限极大中等中等维护成本高低低这张表不是要分出高下而是帮你判断你的场景到底需要哪一列。3. Codex 的记忆机制把项目知识沉淀成文件Codex 这条路线我理解它的设计哲学是项目即记忆。它不追求记住你这个人而是追求记住这个项目。3.1 记忆文件的组织方式Codex 的记忆通常落在项目根目录下的约定文件里最典型的是AGENTS.md这类约定文档。它的内容不是流水账式的对话记录而是结构化的项目知识这个项目用什么技术栈、有哪些约定俗成的规范、构建命令是什么、哪些目录不能乱动。为什么是这种形态因为 Codex 的定位是在代码库里干活的 Agent。它每次进入项目第一件事就是读这些约定文件快速建立对项目的认知。这比让它去向量库里检索这个项目的构建命令是什么要直接得多——构建命令就那么一条检索反而绕远路。我实际用下来的感受是这类文件写得好不好直接决定 Agent 干活的质量。写得含糊它就瞎猜写得具体它就靠谱。这跟带新人是一个道理你给新人的 onboarding 文档越清晰他上手越快。3.2 什么内容值得写进记忆文件这里有个常见的误区很多人把记忆文件当成什么都往里塞的垃圾桶结果文件膨胀到几千行Agent 读都读不完反而稀释了关键信息。我的经验是值得写进 Codex 记忆文件的内容满足两个条件之一高频复用每次任务都要用到的信息比如构建命令、测试命令、代码风格约定容易踩坑不写清楚就会出错的隐性规则比如这个目录下的文件是自动生成的不要手动改。反过来一次性的、临时的、可以从代码里直接推断出来的信息都不该写进去。比如上次我们改了登录逻辑这种属于对话历史不属于项目知识。3.3 实操从零搭一个 Codex 记忆文件假设你接手一个中等规模的 TypeScript 项目想给 Codex 配一套记忆。可以这样组织# 项目约定 ## 技术栈 - 运行时Node.js 20 - 框架Fastify - 数据库PostgreSQL Prisma - 测试Vitest ## 常用命令 - 安装依赖pnpm install - 本地开发pnpm dev - 跑测试pnpm test - 类型检查pnpm typecheck ## 代码规范 - 所有导出函数必须有显式返回类型 - 禁止使用 any必要时用 unknown 类型守卫 - 提交前必须通过 typecheck 和 test ## 禁区 - src/generated/ 下的文件由 Prisma 自动生成禁止手动修改 - 不要直接改 .env改 .env.example 并同步文档这份文件不长但信息密度很高。Codex 读完它基本就知道该怎么在这个项目里干活了。提示记忆文件要定期维护。项目演进后过时的约定比没有约定更危险因为它会误导 Agent。3.4 踩坑记录记忆文件写太满的后果我早期犯过一个错把记忆文件写成了项目百科全书塞进了大量细节。结果发现两个问题一是 Agent 每次读取消耗的上下文变多留给实际任务的预算变少二是关键信息被淹没在噪音里Agent 反而抓不住重点。后来我改成主文件 分文件的结构主文件只放最核心的约定和索引细节拆到子文件里需要时再读。这个思路跟写文档是一样的——先给目录再给内容。4. Claude Code 的记忆机制显式引用与分层沉淀Claude Code 的记忆设计跟 Codex 有相似之处但更强调显式和分层。4.1 CLAUDE.md 的定位Claude Code 最核心的记忆载体是CLAUDE.md文件。它可以在多个层级存在项目根目录、子目录、用户主目录。读取时Claude Code 会把这些层级的文件叠加起来形成一个完整的上下文。这个分层设计很聪明。用户级文件放我个人的通用偏好比如回答用中文代码注释用英文项目级文件放这个项目的约定子目录级文件放这个模块的特殊规则。三层叠加既避免了重复又保证了针对性。我特别喜欢这个设计的一点是它把个人偏好和项目约定解耦了。换项目时个人偏好自动跟着走不用每个项目重配一遍。4.2 记忆的写入时机Claude Code 的记忆写入有两种触发方式显式指令你直接说记住这个它就会把相关内容写进CLAUDE.md自动摘要在长会话中它会把关键决策和结论沉淀下来。这里我要提醒一个实操中的坑自动摘要不是万能的。它摘出来的东西未必是你想要的有时候会把临时性的讨论也记进去。所以我的习惯是重要决策一定用显式指令确认一遍别完全依赖自动。4.3 实操用分层记忆管理多模块项目假设你有一个 monorepo包含前端、后端、共享库三个部分。可以这样组织记忆~/.claude/CLAUDE.md # 个人偏好语言、风格、通用习惯 项目根/CLAUDE.md # 全局约定包管理器、提交规范 项目根/frontend/CLAUDE.md # 前端专属组件规范、状态管理约定 项目根/backend/CLAUDE.md # 后端专属API 规范、数据库约定 项目根/shared/CLAUDE.md # 共享库版本策略、发布流程这样当 Claude Code 在前端目录下工作时它会读到个人偏好 全局约定 前端专属三层既不会漏掉通用规则也不会被后端规则干扰。4.4 一个容易被忽略的细节记忆的优先级分层记忆有个必须搞清楚的问题当不同层级的规则冲突时谁说了算我的实测经验是越具体的层级优先级越高。也就是说子目录规则 项目规则 用户规则。这个顺序符合直觉——越靠近具体场景的规则越应该被尊重。但这也意味着如果你在用户级写了所有代码用 4 空格缩进而项目级写了用 2 空格那在项目里就会用 2 空格。所以配置时要想清楚哪些规则该放哪一层。5. 不用向量库检索问题怎么解决看到这里你可能会问不向量库那从大量记忆里找到相关的那条这件事怎么办这正是文件式路线最需要回答的问题。5.1 全量读取的前提是记忆足够小文件式路线能成立前提是记忆总量控制在上下文窗口能容纳的范围内。这就要求对记忆做严格的管理该摘要的摘要该归档的归档该删的删。这听起来像是个限制但换个角度想它其实是个强制性的好习惯。向量库方案容易让人偷懒——反正都存进去检索时再说。结果就是记忆库越来越臃肿里面塞满了没用的东西。文件式路线逼着你定期清理反而让记忆保持高质量。5.2 用目录结构代替相似度检索文件式路线解决找相关记忆的办法不是算相似度而是用目录结构和命名来组织。你想找构建相关的记忆就去build/目录想找 API 相关的就去api/目录。这是一种人工预分类的思路。它比向量检索笨但胜在确定性。向量检索可能召回不相关的内容目录结构不会——你放哪就是哪。对于结构清晰的项目知识这种确定性比智能更重要。5.3 显式引用让 Agent 主动去读Claude Code 还有个机制我特别喜欢显式引用。你可以在记忆文件里写关于部署流程见docs/deploy.mdAgent 需要时就会去读那个文件。这相当于把检索变成了跳转由 Agent 自己判断需不需要深入。这个机制的关键在于主文件只放索引和摘要细节放在被引用的文件里。这样主文件保持精简细节又不丢失。我把它类比成书的目录和正文——目录让你快速定位正文提供完整内容。5.4 什么时候该考虑上向量库说了这么多文件式路线的好话也得说清楚它的边界。以下情况你应该认真考虑向量库或混合方案记忆条目超过几千条全量读取不现实记忆内容高度非结构化难以用目录分类需要跨用户、跨设备共享记忆需要基于语义的模糊匹配而不是精确的目录定位。判断标准很简单当你发现人工组织记忆的成本超过了维护检索系统的成本时就该换方案了。6. 两条路线的实测对比与选型建议前面讲了原理这一节讲实测。我在两个真实项目里分别用了这两套机制下面是一些具体的观察。6.1 上手成本对比Codex 的文件路线上手几乎零成本——建个文件写点约定完事。Claude Code 的分层机制稍微复杂一点要理解层级叠加和优先级但也就半小时的事。向量库路线呢选库、部署、写 embedding 管道、调切片参数、评估召回质量……我见过最快的团队也花了两三天才跑通一个能用的版本。对于个人项目或小团队这个投入产出比很难看。6.2 长期维护成本对比文件式路线的维护成本主要在人工整理——定期清理过时内容、更新约定、调整结构。这个成本是持续的但每次都不大。向量库路线的维护成本主要在系统运维——数据库要备份、embedding 模型要更新、召回质量要监控。这个成本是间歇性的但每次都不小而且一旦出问题影响面很大。我的体感是小规模场景下文件式路线的总成本明显更低。6.3 记忆质量对比这点可能反直觉文件式路线的记忆质量往往更高。因为每条记忆都是人或 Agent 在人的监督下显式写进去的天然经过了筛选。而向量库方案容易什么都存导致记忆库里噪音很多。当然这个优势的前提是有人认真维护。如果记忆文件也是随便写写那质量一样差。6.4 选型决策表你的场景推荐方案理由个人 CLI 工具、代码助手文件式Codex/Claude Code零基础设施可审计小团队内部 Agent文件式 Git 版本控制记忆跟着代码走面向海量用户的通用助手向量库或混合规模超出文件承载能力需要跨设备同步向量库 云端存储文件同步麻烦记忆高度结构化文件式目录分类足够记忆高度非结构化向量库需要语义检索6.5 一个混合思路其实这两条路线不是非此即彼。我最近在试的一个做法是用文件式管理核心记忆用向量库管理海量历史。核心记忆项目约定、关键决策写在文件里保证 Agent 每次都能读到海量历史对话存进向量库需要时再检索。这样既保住了文件式的确定性和可审计性又突破了上下文窗口的规模限制。目前跑下来效果不错但复杂度也确实上去了适合有一定规模的团队。7. 实操中那些文档不会告诉你的细节最后这部分是我踩坑踩出来的经验纯干货。7.1 记忆文件要写给未来的自己看很多人写记忆文件时默认读者是现在的自己所以写得很简略。但记忆文件的真正读者是未来的 Agent 和未来的你。三个月后你回来看如果看不懂当时为什么这么写那这份记忆就是失败的。我的做法是每条约定后面加一句为什么。比如不写用 pnpm而写用 pnpm因为项目用了 workspacenpm 处理不了。多这一句未来能省很多困惑。7.2 定期做记忆审计我给自己定了个规矩每个月过一遍记忆文件删掉过时的合并重复的补充新踩的坑。这个习惯坚持下来记忆文件一直保持精简高效。不做审计的后果我见过——有个项目的记忆文件半年没动里面一半的约定早就失效了Agent 照着执行反而出错。7.3 敏感信息绝不进记忆文件这是个安全红线。记忆文件可能进 Git、可能被分享、可能被 Agent 读取后输出。所以任何密钥、token、内部地址都不该写进去。需要的话写密钥见环境变量 XXX而不是把值写进去。7.4 记忆的冷热分离不是所有记忆都同等重要。我把记忆分成热记忆每次必读放主文件和冷记忆按需读取放子文件。热记忆控制在几百行以内冷记忆可以无限扩展。这个分离让 Agent 的上下文预算花在刀刃上。7.5 别指望 Agent 自己维护记忆自动摘要、自动写入这些功能很方便但别完全放手。Agent 不知道什么对你重要它只会按自己的判断记。重要的事一定要人工确认。我见过太多Agent 记了一堆没用的真正重要的反而漏了的案例。7.6 版本控制是文件式记忆的隐藏福利因为记忆是文件所以能进 Git。这意味着你可以追溯记忆的演变——什么时候加的这条约定为什么加的一目了然。这个能力在排查Agent 为什么突然行为变了时特别有用。向量库方案要做到这点得额外做版本管理麻烦得多。8. 我个人的一点体会用下来最大的感受是记忆方案的选择本质是对规模和可控性的权衡。向量库换来了规模代价是可控性文件式换来了可控性代价是规模。没有银弹只有匹配。对绝大多数个人开发者和小团队来说我真心建议先从文件式起步。它足够简单足够透明足够你用到项目规模真正变大。等到文件式扛不住了再上向量库也不迟——那时候你对自己的记忆需求已经有了清晰认知选型和调优都会更有方向。反过来一上来就上向量库很容易陷入为了用技术而用技术的陷阱最后维护一堆用不上的基础设施反而拖慢了开发。技术选型这件事够用就好别过度设计。这是我踩了几年坑之后最想分享的一句话。 
长河君 · 2026/11/4 9:37:25 · 阅读 1.2k Agent记忆方案选型：文件式与向量库的工程实践对比
1. 为什么 Agent 的记忆问题值得单独拿出来聊做 Agent 开发的人绕不开一个尴尬的现实模型本身是无状态的。你这一轮跟它聊得再深入下一轮开个新会话它对你一无所知。这不是模型能力问题而是架构决定的——每次推理都是一次独立的函数调用上下文窗口里有什么它就知道什么。于是持久化记忆成了 Agent 从玩具走向生产工具的分水岭。一个只会单轮问答的 Agent 是 demo一个能记住你上周提过的偏好、记得三天前那个未完成任务的 Agent才勉强算得上助手。市面上讲 Agent 记忆的方案十篇里有八篇会把你引向向量数据库把对话切片、embedding、存进 Pinecone 或 Milvus、检索时做相似度召回。这套 RAG 思路确实成熟但它有个隐性成本——你得维护一整套检索基础设施embedding 模型要选型切片策略要调召回质量要评估还得处理检索出来的东西其实不相关这种经典翻车场景。而 Codex 和 Claude Code 这两条路线走的是另一条路不依赖向量库用文件系统和结构化文本做记忆载体。这个选择乍看土但背后有非常清醒的工程判断。我前后在两个项目里分别用过这两套机制踩过一些坑也总结出一些文档里不会写的经验。这篇就把两条路线的设计逻辑、实操细节和适用边界掰开讲清楚。先说结论性的判断方便你对号入座如果你做的是个人开发者工具、CLI 助手、代码库级别的长期协作文件式记忆的性价比远高于向量库如果你做的是面向海量用户、跨会话跨设备的通用助手那向量库或混合方案仍然更合适两者不是替代关系而是不同规模、不同场景下的取舍。下面进入正题。2. 两条路线的底层分歧记忆到底存在哪里要理解 Codex 和 Claude Code 的记忆设计得先搞清楚一个根本问题记忆的存储介质决定了它的检索方式和能力边界。2.1 向量库路线的隐含假设向量库方案的核心假设是记忆条目太多多到无法全部塞进上下文所以必须靠相似度检索来挑出相关的几条。这个假设在什么情况下成立当你的记忆规模达到几千上万条、且条目之间高度异构时它成立。但反过来如果你的记忆总量只有几十条、几百条全部读进上下文完全可行那向量检索带来的收益就非常有限反而引入了 embedding 成本、召回误差和基础设施复杂度。我见过不少团队项目刚起步就上了向量库结果发现召回出来的内容经常驴唇不对马嘴最后还得加一层 rerank再不行就人工规则兜底。这套东西的维护成本远超它解决的问题。2.2 文件式记忆的核心逻辑Codex 和 Claude Code 的共同点是把记忆写成人类可读的文件放在项目目录或用户配置目录里需要时直接读取。这带来几个直接好处可审计你打开文件就能看到 Agent 记住了什么不用去数据库里查可编辑记错了直接改文件不用重新 embedding可版本控制记忆文件能进 Git跟着代码一起演进零基础设施不需要额外部署任何服务。代价也很明显记忆规模受限于上下文窗口。文件太大就读不进来所以必须做摘要、分层和裁剪。这就是两条路线真正开始分道扬镳的地方——它们对如何组织这些文件给出了不同的答案。2.3 一张表看清分歧点维度向量库路线Codex 文件路线Claude Code 文件路线存储介质向量数据库项目内 Markdown 文件项目/用户级 Markdown 文件检索方式相似度召回全量读取 层级组织全量读取 显式引用记忆写入自动切片入库显式指令写入显式指令 自动摘要可审计性低需查库高直接看文件高直接看文件规模上限极大中等中等维护成本高低低这张表不是要分出高下而是帮你判断你的场景到底需要哪一列。3. Codex 的记忆机制把项目知识沉淀成文件Codex 这条路线我理解它的设计哲学是项目即记忆。它不追求记住你这个人而是追求记住这个项目。3.1 记忆文件的组织方式Codex 的记忆通常落在项目根目录下的约定文件里最典型的是AGENTS.md这类约定文档。它的内容不是流水账式的对话记录而是结构化的项目知识这个项目用什么技术栈、有哪些约定俗成的规范、构建命令是什么、哪些目录不能乱动。为什么是这种形态因为 Codex 的定位是在代码库里干活的 Agent。它每次进入项目第一件事就是读这些约定文件快速建立对项目的认知。这比让它去向量库里检索这个项目的构建命令是什么要直接得多——构建命令就那么一条检索反而绕远路。我实际用下来的感受是这类文件写得好不好直接决定 Agent 干活的质量。写得含糊它就瞎猜写得具体它就靠谱。这跟带新人是一个道理你给新人的 onboarding 文档越清晰他上手越快。3.2 什么内容值得写进记忆文件这里有个常见的误区很多人把记忆文件当成什么都往里塞的垃圾桶结果文件膨胀到几千行Agent 读都读不完反而稀释了关键信息。我的经验是值得写进 Codex 记忆文件的内容满足两个条件之一高频复用每次任务都要用到的信息比如构建命令、测试命令、代码风格约定容易踩坑不写清楚就会出错的隐性规则比如这个目录下的文件是自动生成的不要手动改。反过来一次性的、临时的、可以从代码里直接推断出来的信息都不该写进去。比如上次我们改了登录逻辑这种属于对话历史不属于项目知识。3.3 实操从零搭一个 Codex 记忆文件假设你接手一个中等规模的 TypeScript 项目想给 Codex 配一套记忆。可以这样组织# 项目约定 ## 技术栈 - 运行时Node.js 20 - 框架Fastify - 数据库PostgreSQL Prisma - 测试Vitest ## 常用命令 - 安装依赖pnpm install - 本地开发pnpm dev - 跑测试pnpm test - 类型检查pnpm typecheck ## 代码规范 - 所有导出函数必须有显式返回类型 - 禁止使用 any必要时用 unknown 类型守卫 - 提交前必须通过 typecheck 和 test ## 禁区 - src/generated/ 下的文件由 Prisma 自动生成禁止手动修改 - 不要直接改 .env改 .env.example 并同步文档这份文件不长但信息密度很高。Codex 读完它基本就知道该怎么在这个项目里干活了。提示记忆文件要定期维护。项目演进后过时的约定比没有约定更危险因为它会误导 Agent。3.4 踩坑记录记忆文件写太满的后果我早期犯过一个错把记忆文件写成了项目百科全书塞进了大量细节。结果发现两个问题一是 Agent 每次读取消耗的上下文变多留给实际任务的预算变少二是关键信息被淹没在噪音里Agent 反而抓不住重点。后来我改成主文件 分文件的结构主文件只放最核心的约定和索引细节拆到子文件里需要时再读。这个思路跟写文档是一样的——先给目录再给内容。4. Claude Code 的记忆机制显式引用与分层沉淀Claude Code 的记忆设计跟 Codex 有相似之处但更强调显式和分层。4.1 CLAUDE.md 的定位Claude Code 最核心的记忆载体是CLAUDE.md文件。它可以在多个层级存在项目根目录、子目录、用户主目录。读取时Claude Code 会把这些层级的文件叠加起来形成一个完整的上下文。这个分层设计很聪明。用户级文件放我个人的通用偏好比如回答用中文代码注释用英文项目级文件放这个项目的约定子目录级文件放这个模块的特殊规则。三层叠加既避免了重复又保证了针对性。我特别喜欢这个设计的一点是它把个人偏好和项目约定解耦了。换项目时个人偏好自动跟着走不用每个项目重配一遍。4.2 记忆的写入时机Claude Code 的记忆写入有两种触发方式显式指令你直接说记住这个它就会把相关内容写进CLAUDE.md自动摘要在长会话中它会把关键决策和结论沉淀下来。这里我要提醒一个实操中的坑自动摘要不是万能的。它摘出来的东西未必是你想要的有时候会把临时性的讨论也记进去。所以我的习惯是重要决策一定用显式指令确认一遍别完全依赖自动。4.3 实操用分层记忆管理多模块项目假设你有一个 monorepo包含前端、后端、共享库三个部分。可以这样组织记忆~/.claude/CLAUDE.md # 个人偏好语言、风格、通用习惯 项目根/CLAUDE.md # 全局约定包管理器、提交规范 项目根/frontend/CLAUDE.md # 前端专属组件规范、状态管理约定 项目根/backend/CLAUDE.md # 后端专属API 规范、数据库约定 项目根/shared/CLAUDE.md # 共享库版本策略、发布流程这样当 Claude Code 在前端目录下工作时它会读到个人偏好 全局约定 前端专属三层既不会漏掉通用规则也不会被后端规则干扰。4.4 一个容易被忽略的细节记忆的优先级分层记忆有个必须搞清楚的问题当不同层级的规则冲突时谁说了算我的实测经验是越具体的层级优先级越高。也就是说子目录规则 项目规则 用户规则。这个顺序符合直觉——越靠近具体场景的规则越应该被尊重。但这也意味着如果你在用户级写了所有代码用 4 空格缩进而项目级写了用 2 空格那在项目里就会用 2 空格。所以配置时要想清楚哪些规则该放哪一层。5. 不用向量库检索问题怎么解决看到这里你可能会问不向量库那从大量记忆里找到相关的那条这件事怎么办这正是文件式路线最需要回答的问题。5.1 全量读取的前提是记忆足够小文件式路线能成立前提是记忆总量控制在上下文窗口能容纳的范围内。这就要求对记忆做严格的管理该摘要的摘要该归档的归档该删的删。这听起来像是个限制但换个角度想它其实是个强制性的好习惯。向量库方案容易让人偷懒——反正都存进去检索时再说。结果就是记忆库越来越臃肿里面塞满了没用的东西。文件式路线逼着你定期清理反而让记忆保持高质量。5.2 用目录结构代替相似度检索文件式路线解决找相关记忆的办法不是算相似度而是用目录结构和命名来组织。你想找构建相关的记忆就去build/目录想找 API 相关的就去api/目录。这是一种人工预分类的思路。它比向量检索笨但胜在确定性。向量检索可能召回不相关的内容目录结构不会——你放哪就是哪。对于结构清晰的项目知识这种确定性比智能更重要。5.3 显式引用让 Agent 主动去读Claude Code 还有个机制我特别喜欢显式引用。你可以在记忆文件里写关于部署流程见docs/deploy.mdAgent 需要时就会去读那个文件。这相当于把检索变成了跳转由 Agent 自己判断需不需要深入。这个机制的关键在于主文件只放索引和摘要细节放在被引用的文件里。这样主文件保持精简细节又不丢失。我把它类比成书的目录和正文——目录让你快速定位正文提供完整内容。5.4 什么时候该考虑上向量库说了这么多文件式路线的好话也得说清楚它的边界。以下情况你应该认真考虑向量库或混合方案记忆条目超过几千条全量读取不现实记忆内容高度非结构化难以用目录分类需要跨用户、跨设备共享记忆需要基于语义的模糊匹配而不是精确的目录定位。判断标准很简单当你发现人工组织记忆的成本超过了维护检索系统的成本时就该换方案了。6. 两条路线的实测对比与选型建议前面讲了原理这一节讲实测。我在两个真实项目里分别用了这两套机制下面是一些具体的观察。6.1 上手成本对比Codex 的文件路线上手几乎零成本——建个文件写点约定完事。Claude Code 的分层机制稍微复杂一点要理解层级叠加和优先级但也就半小时的事。向量库路线呢选库、部署、写 embedding 管道、调切片参数、评估召回质量……我见过最快的团队也花了两三天才跑通一个能用的版本。对于个人项目或小团队这个投入产出比很难看。6.2 长期维护成本对比文件式路线的维护成本主要在人工整理——定期清理过时内容、更新约定、调整结构。这个成本是持续的但每次都不大。向量库路线的维护成本主要在系统运维——数据库要备份、embedding 模型要更新、召回质量要监控。这个成本是间歇性的但每次都不小而且一旦出问题影响面很大。我的体感是小规模场景下文件式路线的总成本明显更低。6.3 记忆质量对比这点可能反直觉文件式路线的记忆质量往往更高。因为每条记忆都是人或 Agent 在人的监督下显式写进去的天然经过了筛选。而向量库方案容易什么都存导致记忆库里噪音很多。当然这个优势的前提是有人认真维护。如果记忆文件也是随便写写那质量一样差。6.4 选型决策表你的场景推荐方案理由个人 CLI 工具、代码助手文件式Codex/Claude Code零基础设施可审计小团队内部 Agent文件式 Git 版本控制记忆跟着代码走面向海量用户的通用助手向量库或混合规模超出文件承载能力需要跨设备同步向量库 云端存储文件同步麻烦记忆高度结构化文件式目录分类足够记忆高度非结构化向量库需要语义检索6.5 一个混合思路其实这两条路线不是非此即彼。我最近在试的一个做法是用文件式管理核心记忆用向量库管理海量历史。核心记忆项目约定、关键决策写在文件里保证 Agent 每次都能读到海量历史对话存进向量库需要时再检索。这样既保住了文件式的确定性和可审计性又突破了上下文窗口的规模限制。目前跑下来效果不错但复杂度也确实上去了适合有一定规模的团队。7. 实操中那些文档不会告诉你的细节最后这部分是我踩坑踩出来的经验纯干货。7.1 记忆文件要写给未来的自己看很多人写记忆文件时默认读者是现在的自己所以写得很简略。但记忆文件的真正读者是未来的 Agent 和未来的你。三个月后你回来看如果看不懂当时为什么这么写那这份记忆就是失败的。我的做法是每条约定后面加一句为什么。比如不写用 pnpm而写用 pnpm因为项目用了 workspacenpm 处理不了。多这一句未来能省很多困惑。7.2 定期做记忆审计我给自己定了个规矩每个月过一遍记忆文件删掉过时的合并重复的补充新踩的坑。这个习惯坚持下来记忆文件一直保持精简高效。不做审计的后果我见过——有个项目的记忆文件半年没动里面一半的约定早就失效了Agent 照着执行反而出错。7.3 敏感信息绝不进记忆文件这是个安全红线。记忆文件可能进 Git、可能被分享、可能被 Agent 读取后输出。所以任何密钥、token、内部地址都不该写进去。需要的话写密钥见环境变量 XXX而不是把值写进去。7.4 记忆的冷热分离不是所有记忆都同等重要。我把记忆分成热记忆每次必读放主文件和冷记忆按需读取放子文件。热记忆控制在几百行以内冷记忆可以无限扩展。这个分离让 Agent 的上下文预算花在刀刃上。7.5 别指望 Agent 自己维护记忆自动摘要、自动写入这些功能很方便但别完全放手。Agent 不知道什么对你重要它只会按自己的判断记。重要的事一定要人工确认。我见过太多Agent 记了一堆没用的真正重要的反而漏了的案例。7.6 版本控制是文件式记忆的隐藏福利因为记忆是文件所以能进 Git。这意味着你可以追溯记忆的演变——什么时候加的这条约定为什么加的一目了然。这个能力在排查Agent 为什么突然行为变了时特别有用。向量库方案要做到这点得额外做版本管理麻烦得多。8. 我个人的一点体会用下来最大的感受是记忆方案的选择本质是对规模和可控性的权衡。向量库换来了规模代价是可控性文件式换来了可控性代价是规模。没有银弹只有匹配。对绝大多数个人开发者和小团队来说我真心建议先从文件式起步。它足够简单足够透明足够你用到项目规模真正变大。等到文件式扛不住了再上向量库也不迟——那时候你对自己的记忆需求已经有了清晰认知选型和调优都会更有方向。反过来一上来就上向量库很容易陷入为了用技术而用技术的陷阱最后维护一堆用不上的基础设施反而拖慢了开发。技术选型这件事够用就好别过度设计。这是我踩了几年坑之后最想分享的一句话。