Codex Memories 的 11 个配置键：它为什么有时候不生成记忆

2026-08-09

很多人对 Codex（OpenAI Codex）的 Memories 有个想当然的理解：以为它像人一样，聊过就记住了，没记住是「模型不够聪明」。实际不是。在 Codex CLI 里，Memories 是一条有明确闸门的流水线：先要总开关放行，再要生成开关放行，然后一堆数值阈值决定哪些历史会话够格被拿去提炼，最后才轮到模型干活。任何一道闸门没过，你就什么都拿不到——而且它不会报错，因为「这次不生成」在设计上就是正常行为，不是故障。

这篇把这些闸门逐个拆开，重点讲判断依据：每个键该怎么设、看到什么现象该怀疑哪一个、下一步查哪里。

第一道闸：功能本身默认是关的

先说最容易踩的一条。官方《Configuration Reference》里，特性开关 features.memories 的默认值是 false。

也就是说，如果你从没动过配置，Memories 根本没启用，讨论后面那十个键毫无意义。

怎么确认？用只读命令查当前生效值：

codex features list

这条命令会列出已知特性、所处阶段和当前生效状态三列。在 codex-cli 0.147.0（Windows 11）上，我这台机器实测 memories 一行是「阶段 stable、生效值 false」——阶段是 stable，说明功能本身不是实验性的；生效值是 false，说明它就是默认没开。阶段和生效值是两码事，别把「stable」看成「已启用」，这是 features 表最常被读反的地方。

要打开有三种写法，作用范围不一样，选哪个取决于你想影响多久：

# 1) 只影响本次会话，进程退出即失效
codex --enable memories

# 2) 等价写法，用 -c 覆盖配置项（点号表示嵌套路径）
codex -c features.memories=true

# 3) 永久生效：写进 config.toml
codex features enable memories

前两种是临时覆盖，--enable <FEATURE> 官方说明就是等价于 -c features.<name>=true；第三种 codex features enable 会把结果写进 config.toml，属于改文件的操作，团队共用机器时留意这一点。

顺带一个容易误判的实测细节：在 codex-cli 0.147.0（Windows 11）上，即使 memories 生效值是 false，~/.codex/ 目录下依然存在 memories/ 目录和 memories_1.sqlite 文件。看到这两个条目存在，不能推断功能是开着的，得以 codex features list 的生效值为准。

十一个键的全貌

总开关放行之后，真正控制行为的是 memories. 这一组键。官方《Configuration Reference》给出的完整列表如下。先说清这张表怎么读：「默认 / 范围」一列是官方原文照抄（没标的就是官方没给默认值）；「作用」一列是按键名含义做的理解，官方并没有给逐键释义，除 min_rate_limit_remaining_percent 之外都属于推断，以官方说明为准。

键	默认 / 范围（官方原文）	作用（按键名理解，非官方释义）
`memories.generate_memories`	`true`	是否生成记忆
`memories.use_memories`	`true`	是否使用记忆
`memories.disable_on_external_context`	`false`	存在外部上下文时停用
`memories.max_raw_memories_for_consolidation`	256，上限 4096	参与合并的原始记忆条数上限
`memories.max_unused_days`	30，范围 0–365	记忆多久没被用就淘汰
`memories.max_rollout_age_days`	30，范围 0–90	会话记录多老就不再纳入
`memories.max_rollouts_per_startup`	16，上限 128	每次启动最多处理多少份会话记录
`memories.min_rollout_idle_hours`	6，范围 1–48	会话至少空闲多久才纳入
`memories.min_rate_limit_remaining_percent`	25，范围 0–100	剩余额度低于该比例则不生成
`memories.extract_model`	—	抽取阶段使用的模型
`memories.consolidation_model`	—	合并阶段使用的模型

这张表值得慢慢看，因为光是键名和取值范围就已经透露了不少信息：有 extract_model 和 consolidation_model 两个模型键，又有一个「参与 consolidation 的 raw memories 条数上限」，看起来是先抽取、后合并的两段式处理，而不是一次成型。（这层解读同样是按官方键位含义推的，官方文档没有把流程画成图，以官方说明为准。）

下面逐个展开时，我会把「官方原文给了什么」和「我按键名推的是什么」分开写——这类键最容易出的事故，就是把某人的推断当成官方承诺去配。

读和写是两个开关，别混着关

generate_memories 和 use_memories 默认都是 true，很多人以为是一个东西的两种说法，其实它们能独立控制，而且组合起来正好对应四种很实际的用法：

两个都 true：正常模式，边攒边用。
generate_memories = false、use_memories = true：只读不写。已经攒好的记忆继续生效，但不再往里加新东西。接手别人整理好的一套记忆、或者手头这个项目属于一次性的脏活不想污染长期记忆时，用这个。
generate_memories = true、use_memories = false：只攒不用。想先观察一段时间它到底会记下什么，再决定要不要让它影响回答，用这个。
两个都 false：等于停用，但注意这跟 features.memories = false 不完全是一回事——总开关关掉是整套机制不加载，这两个键关掉是机制在跑但两头都不通。真要彻底关，关总开关更干净。

判断依据很简单：「不想让它学新东西」关 generate_memories，「不想让它影响这次回答」关 use_memories。两个键放在一起看，比逐个查文档快得多。

六个数值阈值：真正决定「这次生成不生成」

这是本文的核心。六个数值键里，前两个管淘汰、后四个管准入。

max_unused_days（官方原文：默认 30，范围 0–365） 按键名推断管的是遗忘侧，即一条记忆多久没被用到就不再留着（官方未给该键释义，以官方说明为准）。能直接拿来做判断的是范围本身：下限是 0，说明理论上可以设成极端值。项目周期长、上下文稳定的团队可以调大；一个月换一次技术栈的，保持默认甚至调小反而更干净。

max_raw_memories_for_consolidation（官方原文：默认 256，上限 4096） 按键名推断是一次 consolidation 能吃进多少条原始记忆的上限（同样是推断）。可以确定的是这个上限跟 consolidation_model 是一套的——合并阶段要跑模型，所以把它往 4096 顶不会是免费的。默认 256 对绝大多数人够用。

后面四个按键名看都是准入侧的闸门，也是「为什么这次没生成」最常被怀疑的地方。注意：除最后一个之外，下面三条的行为解释都是我按键名推的，官方文档没给逐键释义，真要下结论请以官方说明为准。

min_rollout_idle_hours（官方原文：默认 6，范围 1–48）：按该键名的含义推断，一份会话记录要空闲够这么多小时才轮得到被处理。如果这层理解成立，那它最反直觉的一点是——刚聊完的会话不会立刻进记忆。所以「聊一轮然后马上去看有没有新记忆」这种验证方式本身就不可靠：你很可能测的是这个阈值，而不是功能好坏。这个推断有个好处，是它可证伪的：把等待时间拉长一天再看，比反复改配置有用。

max_rollout_age_days（官方原文：默认 30，范围 0–90）：按键名推断是给会话记录设的年龄上限。这里真正硬的信息是范围：上限只有 90，比 max_unused_days 的 365 小得多。两个范围放一起看，配置层面留给「老会话」的余地明显比留给「老记忆」的小，想靠调参让它回头消化半年前的历史，顶不上去。

max_rollouts_per_startup（官方原文：默认 16，上限 128）：按键名推断是单次启动的处理份数上限。重度使用者积压几百份会话很常见，若这层理解成立，追平积压就需要反复启动很多次。所以刚打开 Memories 就期望它立刻理解你过去所有的项目，预期本身就偏高。

min_rate_limit_remaining_percent（默认 25，范围 0–100）：这一条不一样，它是这组阈值里唯一有明确判断口径的——默认 25 的含义就是剩余额度低于 25% 时不生成记忆。也正因为如此，它是整篇文章里最值得记住的判断依据——它意味着记忆功能在你额度紧张的时候会主动让路，把配额留给你正在做的正事。所以「我明明开了 Memories，怎么最近几天一条都没新增」的一个高频原因，压根不是配置错了，而是你这段时间用得猛，额度余量长期在 25% 线以下。

想验证是不是这条在挡，可以临时把它压到 0 试一轮：

codex -c memories.min_rate_limit_remaining_percent=0

-c 用点号表示嵌套路径、值按 TOML 解析，这是顶层选项的标准用法。压到 0 相当于取消这道额度保护，只建议用来定位问题，别长期这么挂着——这个默认值 25 是有意设的保护，不是碍事的限制。

还有一个条件开关

disable_on_external_context 的默认值是官方给的 false；键名读下来是「存在外部上下文时停用」，所以默认应当是不停用，设成 true 则是在有外部上下文介入的场合让 Memories 退场（这层理解同样来自键名，官方未给该键释义）。如果你的使用场景经常混入外部输入、又不希望这些内容进入长期记忆，这个键是官方给的开关，不用自己想土办法。

两个模型键：官方没给默认值，就别猜

extract_model 和 consolidation_model 在官方《Configuration Reference》里没有列出默认值。这意味着我没法告诉你「不配就是用某某模型」——那是编的。能确定的只有两点：它们分别对应抽取和合并两个阶段，可以分别指定；不设的话按官方实现走。要用就明确写上，别依赖想象中的默认。

「没生成记忆」的排查顺序

把上面的东西串成一条可执行的链子，按这个顺序查，基本不会走弯路：

先查总开关。 跑 codex features list，看 memories 那一行的生效值。是 false 就到此为止，先开再说。
再确认配置真的被加载了。 跑 codex doctor --summary，看 config 这一行。在 codex-cli 0.147.0（Windows 11）上我实测过一个很有用的现象：故意用 -c 传一段语法不合法的 TOML，doctor 不会崩溃退出，照常跑完，但会打出 ✗ config config could not be loaded - Fix the reported config error, then rerun codex doctor.——本机实测时这一行是出现在输出的 Notes 区（配置正常加载时，config(loaded) 归在 Configuration 分组下），所以别只盯着 Configuration 那一段找。所以「我改了配置怎么没生效」的第一步永远是跑 doctor 看这一行，而不是反复改配置文件。顺带一提，codex doctor --json 官方说明是输出脱敏报告，需要贴给别人看时用它。
查 generate_memories 是不是被谁关了。 尤其是多人共用的机器或者继承来的配置。
查时间维度。 min_rollout_idle_hours 默认 6、max_rollout_age_days 默认 30，按键名推断分别卡的是「太新」和「太旧」两头（推断，以官方说明为准）。实操上就是：别拿刚结束的会话去验证，也别指望它消化很久以前的历史。
查额度。 min_rate_limit_remaining_percent 默认 25，余量在这条线以下时它就是不生成。这条是本文唯一有明确口径的一条，也最隐蔽，因为它跟你的使用强度绑定，昨天好好的今天不生成完全可能。
查积压。 max_rollouts_per_startup 默认 16，按键名推断是单次启动的处理上限；会话攒太多时，产出速度跟不上预期是可以预期的结果。

如果这六步都排除了，那说明问题不在本文覆盖的这些键上，别再继续拧配置——去官方《Memories》页确认当前版本的实际行为（本文没有引用该页内容，这里只是给你指个方向），比瞎试划算。

另外提醒一句关于 --strict-config 的边界：它的作用是「config.toml 里出现本版本不认识的字段时直接报错退出」，但在 codex-cli 0.147.0（Windows 11）上我实测过，故意把键名拼错再跑 --help 这类不进入会话的路径，并不会触发未知字段报错。所以别把 --strict-config 当成拼写检查器来验证 memories. 下的键名——它的校验发生在真正加载配置去跑会话的时候。

一段可以直接抄的配置

如果你想要的是「稳稳当当地攒记忆、但别在额度紧张时抢资源」，可以按下面这样写进 ~/.codex/config.toml（Windows 上路径是 %USERPROFILE%\.codex\config.toml）：

[features]
memories = true

[memories]
generate_memories = true
use_memories = true
max_unused_days = 60
max_rollouts_per_startup = 32
min_rate_limit_remaining_percent = 25

几个选择的理由：max_unused_days 从 30 放宽到 60，是因为跨项目切换时一条记忆隔一个多月才被再次用到很常见，默认 30 天容易把有用的东西淘汰掉；max_rollouts_per_startup 从 16 提到 32，是给积压的会话一个追赶速度，上限是 128，但一次吃太多会把开销集中到启动那一下；min_rate_limit_remaining_percent 保持默认 25，不动它——这是保护你正事的那道闸。以上为按官方文档键位组合的示例，未逐项实测，以官方文档为准。

什么情况下该主动关掉它

不是所有人都该开 Memories。至少这几种情况值得再想想：

一次性的脏活：临时排查、大规模重构试验、给别人的仓库救火。这类会话的上下文不代表你的长期习惯，攒进去反而是噪声。把 generate_memories 设 false、保留 use_memories，是比整体关掉更精细的做法。
共用机器 / 共用配置：记忆是跟着 CODEX_HOME 走的，多人共用同一份配置时，谁的习惯会被记下来是笔糊涂账。
磁盘已经吃紧：在 codex-cli 0.147.0（Windows 11）上，我这台机器 codex doctor 的 Notes 区提示 rollouts 占用 3.07 GB，~/.codex/ 下单个 SQLite 日志库就有 763 MB。Memories 的原料就是这些会话记录，开着它意味着这部分数据你得留着。磁盘紧张时，这是个要算进去的成本。

最后重申一遍最容易踩的两条：功能默认是关的，以及**「这次没生成」多半是阈值在按设计工作，不是坏了**。把 codex features list 和 codex doctor --summary 这两条只读命令用顺手，比对着文档逐条猜快得多。