给 Codex 加记忆：MemoraX Code 实现跨会话上下文持久化实战

给 Codex 加上记忆这个需求听起来不大但在多文件改造、跨天修复 bug、同时切换 Claude Code 的真实工作流里它直接决定一个 CLI 能不能真正进入日常开发。MemoraX Code 就是围绕这个问题出现的一层记忆扩展它把 Codex 的关键上下文抽出来存成结构化记忆文件并在新会话启动时自动放回对话里让 Codex 看起来像“记住了上一次聊到哪”。我基于 Codex × Claude Code 的实测环境把 MemoraX Code 的安装、配置、验证和常见报错整理成一条可复现的链路。无论你只用 Codex还是同时使用 Claude Code 与 cc-switch 切换模型服务都可以按这篇文章的顺序操作先跑通最小记忆流程再逐步处理生产场景。1. 先理解 Codex 的“记忆”到底缺在哪1.1 一次对话一个会话Codex CLI 的基础工作方式Codex CLI 本质上是一个运行在终端里的编码代理。它读取项目文件、接收用户自然语言指令然后调用模型服务执行文件修改、命令执行等任务。模型本身有上下文窗口所以在一次会话中Codex 可以记住你刚才说过的话。但会话结束后这段对话历史默认不会成为下一次会话的输入新会话打开时模型看到的是项目文件加上当前 prompt而不是上一次的完整对话记录。即使部分版本提供了 resume 或继续会话的能力这也只能恢复一条会话链无法解决跨任务、跨项目、跨工具共享上下文的问题。这种设计对“一次聊完”的简单任务没有问题但实际工程里很少有一次完成的编码任务。需求会拆成两天任务会分给不同人同一个项目还会在 Codex 和 Claude Code 之间来回切换。缺少持久记忆就成了效率瓶颈。1.2 没有持久记忆时的典型痛点可以先把常见痛点列成一张表后面所有方案都会围绕这些痛点展开。场景没有记忆时的表现跨天继续开发重新打开 Codex 后要手动粘贴任务背景和已做决定多分支并行两个任务改到一半切换回来要重新描述上下文团队交接同事用 Codex 分析到一半你不知道他做过哪些判断切换 Claude Code在 Codex 里讨论完方案切到 Claude Code 后又要重新复述控制 token 消耗每次重新描述环境与需求会浪费大量模型输入 token这些痛点的本质是上下文存在“会话内存”里没有落到项目可读取、可提交、可比较的持久存储中。只要把关键上下文从会话里搬到文件里并在新会话启动时重新注入问题就解决了。这个思路也是 MemoraX Code 的核心机制。1.3 MemoraX Code 解决什么问题记忆层与上下文注入MemoraX Code 做的事情可以概括为两层。第一层是“写入”在 Codex 对话过程中把任务目标、技术决策、已完成动作、失败原因等内容用命令写成结构化记忆。第二层是“读取”在 Codex 启动新会话前把记忆文件转换为一段 prompt合并进用户输入或系统指令让模型从第一步就看到这些上下文。在这个位置里MemoraX Code 不是替代 Codex也不是修改模型服务而是一层夹在 CLI 与项目之间的记忆中间件。它读写的不是盲目的全量日志而是经过筛选的“有用上下文”。比如“为什么选择这个方案”“这个文件不能动”“上次改到哪一步失败”这些信息比完整聊天记录更有价值也更适合长期保存。2. 方案总体设计Codex × Claude Code 如何共享一套记忆2.1 关键组件与整体链路要让 Codex 和 Claude Code 共享一套记忆通常需要有四类组件协同工作Codex CLI主编码代理负责执行文件修改和命令任务。Claude Code另一个 CLI适合代码评审、架构讨论和长链路分析。cc-switch管理 Codex 和 Claude Code 的模型服务配置让两个 CLI 可以切换到同一个相容模型服务。MemoraX Code统一的记忆读写层向下管理记忆仓库向上提供注入 prompt 和查询接口。整体流程大致是在 Codex 或 Claude Code 中对项目做关键决策通过 MemoraX Code 写入记忆下一次无论启动 Codex 还是 Claude Code都先从记忆仓库导出当前任务上下文注入到新会话任务完成后再把最终结果摘要写回记忆。这种设计的最大好处是记忆不属于某一个 CLI而属于项目。只要.memorax/目录在项目仓库里换工具、换机器、换同事都能复用。2.2 记忆存储结构task、decision、command、risk记忆文件如果只是堆聊天记录本质上还是一堆噪音。建议在 MemoraX Code 里按“结构化条目”保存每条记忆至少包含类型、内容、时间和标签。常见的类型包括task当前任务是什么。decision已经确认的技术决策。command继续工作时需要知道的命令、路径、依赖。risk容易踩的坑和注意事项。以 JSON 配置为例一个最小记忆配置长这样{ version: 1, store: .memorax, autoInject: true, maxMemoryTokens: 2000, types: [task, decision, command, risk], ignoreFiles: [.git, node_modules, dist] }配置里的store指定记忆目录autoInject控制在会话启动时是否自动注入记忆maxMemoryTokens限制注入的 token 总量防止记忆过长把模型输入窗口撑爆。实际项目里还可以加入project字段区分不同项目。对应的一段记忆内容可以保存为 Markdown--- session_id: 20250612-001 project: order-service created_at: 2025-06-12T10:30:0008:00 tags: [refactor, order] --- ## task 将订单状态机的判断逻辑从 service 中抽到独立模块。 ## decision 使用独立的 OrderStateMachine 类不在 service 里堆 if/switch。 ## command - 新模块目录src/main/java/com/example/order/state - 需要补充状态流转测试用例 ## risk 不要把业务日志放在状态机内部否则后续想换日志框架会很难。这种结构的好处是Codex 能一眼看懂关键信息Claude Code 也能正常读取Git 也能记录变更历史。2.3 注入机制启动注入与会话内写入在实测中MemoraX Code 通常支持两条注入路径。一条是启动注入在 Codex 启动前先执行memora export --format prompt得到一段记忆文本再通过命令行参数或 hooks 把它并进用户输入。这样新会话的第一个 prompt 就带上了旧会话的关键结论。另一条是会话内写入在对话中调用记忆命令比如memora add把当前讨论出的方案写入记忆文件这样即使会话中断结论也不会丢。如果是 Claude Code则可以额外利用CLAUDE.md。很多开发者会把项目级记忆放在CLAUDE.md里MemoraX Code 可以把记忆导出为该格式让 Claude Code 自动读取。需要提醒的是不同版本的 MemoraX Code 对autoInject的具体实现可能有差异落地前先确认你当前版本的 hooks 和 prompt 拼接方式。3. 环境准备与安装3.1 版本与前置依赖核对开始安装前建议先核对环境。下面的版本要求是常见项目里的基线具体以工具当前文档为准。依赖学习环境最低要求生产环境建议Node.js18当前 LTS 版本安装时加入 PATHnpm自带使用 npm ci 锁定依赖时注意版本Git2.x配合代码仓库管理记忆文件Codex CLI最新稳定版与团队统一版本Claude Code最新稳定版按需安装不强制cc-switch可选需要切换模型服务时使用检查本机版本的命令可以先在终端跑一遍node -v npm -v git --version确认基础环境没问题后再装 CLI。若 Node 版本过低Codex 或 Claude Code 安装时可能直接报错。3.2 安装 Codex CLICodex CLI 的安装方式以 npm 为例npm install -g openai/codex codex --version安装完成后建议先跑一次codex确认它能正常连接你所使用的模型服务。如果这一步用到自定义网关先确认配置里的endpoint和model与网关支持范围一致再进入下一步。3.3 安装 Claude Code可选但推荐同时使用 Claude Code 时安装命令类似npm install -g anthropic-ai/claude-code claude --versionWindows PowerShell 安装时常见报错有两种一种是npm找不到说明 Node.js 安装后没有刷新 PATH重启终端或手动加入环境变量即可另一种是“无法加载 claude.ps1因为在此系统上禁止运行脚本”这属于 PowerShell 执行策略限制。可以只在当前用户范围放开Set-ExecutionPolicy -Scope CurrentUser RemoteSigned设置后重开终端再执行claude --version。注意不要为了省事直接关掉全局执行策略也不要用未知来源的安装包尽量走 npm 官方渠道。3.4 安装与初始化 MemoraX CodeMemoraX Code 的安装方式取决于发布形态。常见做法是作为 npm 包安装npm install -g memorax-code memora --version不同版本的 MemoraX Code 命令名可能不同。这里以memora为例实际以你安装版本的--help输出为准。然后进入目标项目目录初始化记忆库cd /path/to/your-project memora init --project .初始化完成后目录下会出现.memorax/文件夹和memora.config.json配置。建议把.memorax/一并提交到 Git这样团队里的其他成员也能看到 shared memory。若项目有node_modules、dist、logs等目录确认配置里的ignoreFiles是否包含它们。4. 最小可运行案例让 Codex 记住一个需求4.1 初始化项目与记忆库从最小闭环开始我用一个订单服务项目举例。先初始化项目记忆库cd /path/to/order-service memora init --project order-service执行后目录结构类似order-service/ ├── .memorax/ │ ├── config.json │ ├── sessions/ │ └── index.md ├── memora.config.json └── src/...config.json保存记忆库配置sessions/保存按会话拆分的记忆文件index.md可以当作一个所有记忆的摘要索引。4.2 写入第一条记忆假设任务是“把订单状态机的判断逻辑从 service 中抽到独立模块”。先写入任务再写入决定memora add --type task --content 将订单状态机的判断逻辑从 service 中抽到独立模块 memora add --type decision --content 使用独立 OrderStateMachine 类不在 service 里堆 if/switch也可以一次性加入标签方便后续检索memora add --type decision \ --content 所有订单状态流转必须经过 OrderStateMachine.validate() \ --tag refactor --tag order写完可以用memora list查看当前记忆列表。如果输出能看到刚写入的两条记录说明写入成功。4.3 在新会话里让 Codex 恢复上下文现在关闭当前 Codex 会话重新打开一个终端把记忆导出成 promptmemora export --format prompt如果输出内容正常就可以把它拼到 Codex 的启动指令里codex 继续我们上次的任务这是记忆上下文 $(memora export --format prompt)在 Windows PowerShell 里命令替换写法也是$(...)但要注意引号内换行是否被正确保留。若你的 Codex 版本支持--prompt-file可以先生成到临时文件再传入避免 shell 转义问题memora export --format prompt /tmp/codex-memory.md codex --prompt-file /tmp/codex-memory.md4.4 验证记忆是否生效启动新会话后向 Codex 问一句“根据记忆告诉我当前任务是什么上一个决定是什么。”正确的期望是它回答出“任务是把订单状态机抽取到独立模块”以及“决定是使用 OrderStateMachine 类”。这能证明记忆确实进入了模型上下文。更自动化的检查方式是用memora show latest查看最近一条记忆确认写入时间、类型和内容再用memora export反向确认可见内容。如果 Codex 的回答和记忆文件不一致先不要怀疑模型先检查注入环节有没有拼错。注意不要只验证程序能启动还要验证新会话是否真正“看到了”记忆。只启动但答不出记忆内容说明注入链路有问题。5. 与 Claude Code 协同以及和 cc-switch 的联动5.1 Codex 和 Claude Code 的分工两者不是互相替代的关系。实际项目中我通常用 Codex 做文件修改类和任务执行类操作用 Claude Code 做代码评审、架构梳理和长链路分析。它们都能读写文件、执行命令但工作习惯和提示词风格不一样适合在同一项目里配合使用。维度CodexClaude Code安装方式npm i -g openai/codexnpm i -g anthropic-ai/claude-code常用场景代码修改、多文件编辑、执行测试架构讨论、评审、代理任务、使用 CLAUDE.md记忆方式由 MemoraX Code 注入CLAUDE.md MemoraX Code 注入配置入口~/.codex/config.toml~/.claude/settings.json会话恢复尽量通过记忆文件恢复上下文支持多种方式但长期记忆仍建议落到文件在这套组合里MemoraX Code 是记忆的唯一来源两个 CLI 都通过它读写避免各自维护一套上下文。5.2 用 cc-switch 切换模型服务cc-switch 解决的是“多模型服务切换”的问题。Codex 和 Claude Code 都可以配置不同的接口地址、模型名和密钥。手工改这些配置很容易改错cc-switch 把常用配置整理成 profile切换时一键替换。对于需要频繁在本地开发、测试环境、不同模型服务之间切换的场景它能减少配置事故。如果使用的是 DeepSeek、Ollama 这类相容服务需要额外确认它们是否支持 Codex 所依赖的接口端点。/responses和传统补全接口并不总是一回事模型不支持时报错通常会是“模型不支持”或者“请求转发失败”这两类。切换后要重点检查三处base_url是否指向当前 profile 的地址model是否在当前地址支持列表里api_key是否有效。很多“请求失败”的报错都是只切了 profile 名称但 CLI 仍在读旧的配置文件。配置文件示例中的关键项通常会类似下面这样实际字段名以你使用的版本为准model gpt-x base_url http://localhost:8080/v1 api_key your-api-key如果你发现 switch 后codex仍然访问旧服务先检查环境变量是否覆盖了配置文件再检查 CLI 启动目录是否加载了项目级配置。5.3 同一份记忆在两个 CLI 间复用因为记忆属于项目而非某个 CLI所以复用非常简单。在 Codex 里写好的记忆切到 Claude Code 时导出成它更容易读取的格式memora export --format claude CLAUDE.md之后启动claudeClaude Code 会读取项目里的CLAUDE.md等于把你之前和 Codex 讨论出的结论带入新会话。注意不要每次全量覆盖CLAUDE.md可以先看 diff 再提交避免旧结论被新任务冲掉。5.4 参数与提示词模板示例为了控制模型每次都按统一方式处理记忆可以在memora.config.json里配置注入模板{ injectTemplate: 以下是从项目记忆库中恢复的上下文请优先阅读\n{{memories}}\n现在请继续完成当前任务。 }这个模板的意义是告诉模型“这些不是普通聊天内容而是需要优先遵守的既有上下文”。如果省略模板记忆内容直接拼在用户输入后面模型可能把它当成普通补充优先级不够。6. 实测中的常见报错与排查链路6.1 cc-switch 网关在 Codex/responses接口上报错网上和实际开发中常见的一条报错是cc-switch local gateway failed while handling codex endpoint /responses。这里所说的 local gateway 实际是指本地转发服务或网关报错含义是网关在处理 Codex 的/responses请求时失败了。可能原因包括网关没启动或端口已被占用。当前 profile 指向的模型服务不支持/responses端点。模型名不在服务支持列表内网关返回模型不支持。api_key为空网关转发请求时鉴权失败。排查时先按这个顺序走cc-switch list cc-switch use profile-name curl http://localhost:8080/v1/responses -X POST -d {model:your-model} -H Authorization: Bearer your-key如果 curl 返回 401问题在密钥如果返回 model not supported问题在模型如果连接不上问题在网关进程或端口。修复后再回到codex重试。问题现象常见原因检查方式处理建议/responses请求失败网关未启动或端口异常看进程、看端口占用重启网关换一个未占用端口请求返回模型不支持模型名不在当前端点支持范围curl 直接调端点换支持/responses的模型鉴权失败api_key 失效或为空看日志中 401重新生成密钥并更新 profile切 profile 后仍报旧地址环境变量或缓存覆盖配置envgrep CODEX6.2 Codex 报模型不支持另一种常见报错类似the gpt-x model is not supported when using codex with a ...。它说明当前 Codex 使用的是/responses接口但所选模型不在该接口的支持列表里。处理方式不是绕开检查而是确认当前模型服务到底支持哪些端点。若项目必须使用某个模型需要确认该模型是否提供对应的兼容端点或调整 Codex 配置使用更合适的模型名。这里最容易踩的坑是在 UI 或 profile 里改了模型但 Codex 配置里还写着旧模型。检查~/.codex/config.toml或项目级配置确保只有一个生效的model值。6.3 Claude Code 安装与订阅权限报错Claude Code 安装报错不一定出在 Claude Code 本身。常见情况有三种PowerShell 无法执行claude.ps1按 3.3 的Set-ExecutionPolicy处理。claude命令找不到重新检查 Node.js 的 npm 全局目录是否在 PATH。登录权限问题如果你看到your organization has disabled claude subscription access for claude code通常是组织策略关闭了 Claude 订阅在 CLI 中的访问。这不是本地能绕过的需要联系组织管理员开通或改用 API key 登录方式。遇到权限类报错时先看是本地脚本问题还是服务端授权问题。本地脚本问题通常伴随“无法加载”“找不到命令”关键词服务端授权问题通常带有organization、subscription、access等关键词。6.4 Codex 无法登录或桌面版打不开Codex 登录页加载慢或桌面版打不开先按这个顺序排查确认 Node.js 和 Codex CLI 版本。查看 Codex 官方登录入口是否可达网络是否正常。清除本地缓存后重新登录。如果是桌面版先升级到最新版本检查操作系统兼容性。查看 Codex 日志定位是登录服务的问题还是本地启动的问题。不要一上来就重装系统或反复删配置先确认日志中的具体错误码再搜对应的错误信息。6.5 记忆不生效的排查顺序如果 Codex 回答里完全看不到记忆内容按以下顺序排查memora list确认记忆确实存在。memora export --format prompt确认导出的文本包含预期内容。检查memora.config.json的autoInject是否为true以及maxMemoryTokens是否过小。确认 Codex 启动时使用的 project 目录与记忆库在同一个目录。确认 shell 拼接没有把空字符串传进去先运行导出命令看实际输出。如果配置了ignoreFiles确认记忆文件没有被忽略。检查是否在错误的 Git 分支或子目录启动 Codex记忆与当前任务不一致。这条链路从“数据是否存在”一路检查到“最终用户是否收到”能覆盖大多数注入失败问题。7. 生产环境使用建议与扩展方向7.1 记忆文件版本管理与备份.memorax/应该像代码一样纳入版本管理。每条记忆有清晰的追加记录合并冲突时可以按 session 文件处理。建议约定每次只追加、不随意修改历史记忆必须修改时先打开文件看 diff避免覆盖关键决定。若记忆库要交给团队共享还要约定谁来负责清理过时记忆。7.2 敏感信息隔离记忆内容里很容易混入数据库地址、账号密码、密钥等敏感信息。不要把这些信息写进--content即使项目是私有仓库也不建议明文保存。可以在记忆类型里增加reference只记录“密钥存放在哪个环境变量”而不是真实值memora add --type reference --content 订单服务的数据库密码读取 DB_PASSWORD 环境变量不写入代码生产环境还可以在导出 prompt 前过滤secret标签确保注入给模型的记忆不包含敏感值。7.3 token 控制与上下文裁剪记忆不是越多越好。模型上下文窗口有限记忆太长会稀释当前任务的注意力也浪费 token。建议设置maxMemoryTokens并定期把旧会话压缩成摘要。比如只保留最近 5 条关键决策把已完成任务归档到archive/目录。可用配置示例{ autoInject: true, maxMemoryTokens: 1500, archiveAfterDays: 7 }archiveAfterDays的含义是超过 7 天的记忆不进当前自动注入但保留在记忆库中需要时手动查询。7.4 接入 MemoraX Code 的检查清单接入前可以按这份清单逐项确认[ ] Node.js、npm、Git 版本满足要求[ ] Codex CLI 可正常启动[ ] Claude Code 按需安装并可运行[ ]memora init --project .执行成功[ ] 写入三条以上不同类型记忆[ ]memora export --format prompt输出正确[ ] Codex 新会话能回答出记忆内容[ ] 与 cc-switch 切换 profile 后重新验证注入[ ] 检查记忆文件无敏感信息[ ] 配置好maxMemoryTokens[ ].memorax/已提交 Git 或纳入备份7.5 下一步扩展方向让 Codex 记住上下文只是第一层。再往下可以按模块拆分记忆让不同任务只注入相关片段也可以结合标签检索只挑出当前业务域的记忆还可以把记忆库变成团队共享资源让评审、重构、排障都基于同一份上下文。对于个人开发来说先做到“跨会话能恢复任务、跨工具能共享决定”就已经能明显减少重复描述和 token 浪费。稳定之后再把记忆清理、敏感信息过滤和自动摘要逐步加上形成一套可维护的项目记忆体系。