第 5 章 · M5 长期记忆
第 5 章 · M5 长期记忆
- 5.1 M5 功能说明:换会话也记得约定和纠正
- 5.2 M5 总体架构:包结构与组件协作
- 5.3 AGENT.md:人写的项目约定(位置与加载)
- 5.4 auto memory:索引 + 主题文件(渐进式披露)
- 5.5 自动记忆存储目录 + 加载 MEMORY
- 5.6 记忆写入:四种类型 + 什么不该写进记忆
- 5.7 两步保存、写入自动放行、主动保存 vs 兜底提取
- 5.8 轮末补充提取(触发时机、互斥、受限回合、提示词)
- 5.9 memory 命令 + 配置
5.1 M5 功能说明:换会话也记得约定和纠正
本篇涉及到的源码列表:
com.minicc.memory.AgentMemory.java
com.minicc.memory.AutoMemory.java
com.minicc.context.MemoryStage.java
com.minicc.permission.ApprovalHook.java
com.minicc.cli.command.MemoryCommand.java
M4 我们做完了,现在这个 Agent 已经能把一次会话完整地写进磁盘,关掉终端再 /resume 就能接着上次继续。
但它还有一个很明显的局限:它记住的只是"这一次会话的过程"。
你昨天纠正过它一次做法,今天开一个新会话,它不会记得这次纠正,你得把同样的话再说一遍。
从这一章开始,我们进入第五个里程碑 M5,为 Agent 增加"跨会话的记忆"。
持久化和记忆不是一回事
我们先把一个容易混淆的点说清楚。
M4 的持久化,解决的是"把某一次会话的过程存下来,下次还能继续"。
M5 的记忆,解决的是另一件事:把"跨会话都该记住的知识"沉淀下来。
比如项目要用 BigDecimal 存金额、集成测试不要 mock 数据库,这类约定不该绑在某一次会话里,而应该每次都自动带上。
M5 这一版交付什么
M5 要做两路长期记忆,再加一个查看命令。这几部分合起来,让 Agent 第一次有了跨会话的连续性。
AGENT.md:人写的项目约定。构建命令、代码风格、接口约定等由人维护,放在项目目录下的.mcc/AGENT.md、随仓库提交,会话一开始就整份读进上下文。- auto memory:模型自己写的笔记。入口文件
MEMORY.md是一个索引,会话开始时整份加载;真正的内容拆在一个个主题文件里,模型判断相关时再自己去读。记忆分四种类型,保存分两步,每轮对话结束后还会补做一次提取兜底。 /memory命令:查看和编辑这些记忆文件。
这一版完成之后,昨天你纠正它"集成测试别 mock 数据库",今天新会话里它依然记得。
命令行里是什么样的
我们用一个跨越两次会话的例子来看。符号沿用前几章:行首的 ⏺ 是一步动作,⎿ 是这一步的结果。
我们先看第一次会话。你让它改一处持久层相关的代码,并纠正了它一次做法。
> 给 OrderRepository 补一个按手机号查订单的集成测试
⏺ 我先写一个连接内存库的测试,用 mock 替换 DataSource……
> 别 mock 数据库。上个季度我们因此出过问题:mock 的测试通过了,真实迁移在生产环境失败了
⏺ 明白了,我改成连真实的测试库来写。这一条我记下,以后涉及持久层的测试都这样处理
⏺ Write(file_path=~/.mcc/projects/-Users-wangzheng-codecrush/memory/feedback_testing.md)
⎿ · 已保存记忆:feedback_testing.md
⏺ Edit(file_path=~/.mcc/projects/-Users-wangzheng-codecrush/memory/MEMORY.md)
⎿ · 已保存记忆:MEMORY.md这里要注意,这两次写记忆都没有弹出审批卡片。因为记忆文件是 Agent 自己的笔记,不修改你的业务代码,所以直接放行。
第二天你重开 mcc,开一个全新的会话,再让它做一个涉及集成测试的任务。
> 再给 OrderRepository 加一个按状态查询的集成测试
⏺ 我先看一下记忆里相关的约定
⏺ Read(file_path=~/.mcc/projects/-Users-wangzheng-codecrush/memory/feedback_testing.md)
⎿ 集成测试必须连真实数据库,不要 mock……
⏺ 按你之前确定的约定,这个测试我直接连测试库来写,不使用 mock你不用再纠正第二遍。它在会话开始时加载了 MEMORY.md 索引,看到有一条和当前任务相关,就自己去读了那个主题文件。
这些文件人也能打开查看,也能修改。在会话里输入 /memory,它会显示一张编号卡片,列出当前能编辑的记忆文件。你输入编号,就用 $VISUAL 或 $EDITOR 指定的编辑器打开。
还是上面这个订单项目。你想核对昨天记下的那条"别 mock 数据库":
> /memory
选择要查看/编辑的记忆文件:
1. 项目约定 AGENT.md(尚未创建)
2. 记忆索引 MEMORY.md
3. 主题 feedback_testing.md
请选择 [1-3]:3
已用 vim 编辑:~/.mcc/projects/-Users-wangzheng-codecrush/memory/feedback_testing.md你选 3 之后,编辑器会接管当前终端。这里假设 $EDITOR 是 vim,所以回执里写的是 vim。你修改完保存并退出,才会回到 mcc。
第 1 项哪怕文件还不存在也会列出来,后面标着"(尚未创建)"。你选它时,程序会先在项目的 .mcc 目录下创建一个空的 AGENT.md(目录还不存在就一并建好),再交给编辑器。第一次写项目约定,也可以从这里进入。
请选择 [1-3]:1
已用 vim 编辑:/Users/wangzheng/codecrush/.mcc/AGENT.md你保存并退出之后,不需要重新打开程序。下一条消息会重新读取 AGENT.md 和 MEMORY.md。主题文件则要等模型下次去读的时候,才会看到你改过的内容。
已经有 ~/.mcc/AGENT.md 时,清单会在项目约定后面多一项"全局约定 ~/.mcc/AGENT.md"。这个文件如果不存在,清单里就不列出。
如果没有设置 $VISUAL 和 $EDITOR,你选完编号之后,它不会自行选择编辑器,只把路径打印出来。
未设置 $VISUAL / $EDITOR,请手动打开:/Users/wangzheng/codecrush/.mcc/AGENT.md你在"请选择"那一行按 Ctrl-C,这次选择就取消了。终端会打印出"已取消。",当前会话还在。
AGENT.md 也是这样自动带上的
人写的约定在 <项目>/.mcc/AGENT.md:
# 项目约定
- 金额字段一律使用 BigDecimal。
- 改完代码要运行 `mvn -q test` 验证。之后每一次会话,Agent 都会在开头把它整份读进上下文。你新增金额字段时它会用 BigDecimal,改完会主动运行测试,不需要你每次再说明。
两路记忆:谁写、存在哪
我们用一张表把它们和"不是长期记忆的东西"放在一起对比,这是本章最重要的概念区分。
| 谁维护 | 存在哪 | 随仓库提交 | 何时加载 | |
|---|---|---|---|---|
AGENT.md | 人 | .mcc/AGENT.md | 是 | 会话开始,整份读入 |
| auto memory | 模型 | ~/.mcc/projects/<项目>/memory/ | 否 | 开始加载 MEMORY.md 索引,主题文件按需读 |
| 待办(M2 / M4) | 模型 | ~/.mcc/.../<id>.todos.json | 否 | 本次会话内;/resume 读快照 |
| 会话日志(M4) | harness | ~/.mcc/.../<id>.jsonl | 否 | 本次会话内;/resume 时回放 |
前两路的共同点,是都在会话开始时加载进上下文,都只记跨会话还值得复用的知识。
后两行跟着同一次会话走,你新开一次会话时不会自动带上。待办在 M2 里先记在会话状态中;M4 又把当前列表整份覆盖写成 <id>.todos.json,和这次会话的日志放在同一个目录。关掉终端之后,/resume 直接读这份快照,不用从日志里重算。
本章的学习路线
接下来的几节,我们把上面这些能力逐节细化成代码。
- 5.2 我们先讲总体架构:M5 复用 M1–M4 的哪些结构、新增了哪个包、一次"带记忆的会话"怎么走。
- 5.3 我们讲
AGENT.md:位置、加载顺序,以及它在上下文里的样子。 - 5.4 我们讲 auto memory 的核心思路:为什么是"索引 + 主题文件",也就是渐进式披露。
- 5.5 我们讲记忆目录怎么布局、
MEMORY.md怎么加载(上限截断)、注入上下文后是什么样。 - 5.6 我们讲记忆写入:四种类型分别记什么,以及什么不该写进记忆。
- 5.7 我们讲两步保存、写入为什么自动放行,以及主动保存和兜底提取的分工。
- 5.8 我们讲每轮结束的补充提取:触发时机、互斥、受限回合和提示词。
- 5.9 我们讲
/memory命令,最后再讲一下配置。
读完这一章,这个 Agent 就能跨会话记住项目约定和你纠正过它的事情,不用每次从零开始。
5.2 M5 总体架构:包结构与组件协作
本篇涉及到的源码列表:
com.minicc.memory.MemoryPromptText.java
com.minicc.memory.AutoMemory.java
com.minicc.memory.AgentMemory.java
com.minicc.memory.MemoryExtractor.java
com.minicc.context.MemoryStage.java
com.minicc.persistence.SessionPaths.java
com.minicc.tool.ToolContext.java
com.minicc.permission.ApprovalHook.java
com.minicc.agent.AgentLoop.java
com.minicc.cli.Renderer.java
com.minicc.cli.command.MemoryCommand.java
com.minicc.MccApplication.java
上一节我们把 M5 要做什么、在命令行里是什么样讲清楚了。
这一节我们来看它的整体结构:复用 M1–M4 的哪些结构、新增了哪个包、一次"带记忆的会话"怎么在各组件之间流动。
你先掌握这张结构图,后面几节逐个讲每个组件时,你就知道它在整体里处在什么位置。
M5 几乎全是新增
M5 延续"后续里程碑只新增、少改动既有代码"的原则。
它的主体是一个新的 memory 包,加一个新的 Stage,对既有代码只有几处很小的修改。
这不是巧合,而是前面几个里程碑提前留好扩展点的回报。我们把 M5 的三条主线分别挂到这些扩展点上。
- 记忆的"加载":M1 的上下文组装器
ContextAssembler内部是一条"有序、可插入 Stage"的管线,我们新增一个MemoryStage插入这条管线,不需要修改既有 Stage。 - 记忆的"读写":不新造工具,模型加载主题文件走 Read,保存记忆走 Write,和改业务代码用的是同一套工具。
- 记忆的"目录":挂在 M4 引入的
stateDir(~/.mcc)结构下,复用 M4 的SessionPaths。
包结构的增量
M5 是建在 M4 之上的,所以我们重点看它相对 M4 新增和修改的部分。
mini-claude-code/
├─ src/main/java/com/minicc/
│ ├─ memory/ // 新:整个包(长期记忆这一件事)
│ │ ├─ MemoryPromptText.java // 新:四类型/什么不该存/两步保存等行为说明常量
│ │ ├─ AutoMemory.java // 新:记忆目录门面(保证目录存在、读 MEMORY.md 索引)
│ │ ├─ AgentMemory.java // 新:读取人写的 AGENT.md
│ │ └─ MemoryExtractor.java // 新:每轮结束的补充提取
│ ├─ context/
│ │ └─ MemoryStage.java // 新:Stage,装载 AGENT.md + 记忆说明 + MEMORY.md
│ ├─ persistence/
│ │ └─ SessionPaths.java // 改:新增 memoryDir(projectRoot)
│ ├─ tool/
│ │ └─ ToolContext.java // 改:新增 memoryDir 与 memoryWritesOnly 字段
│ ├─ permission/
│ │ └─ ApprovalHook.java // 改:写入放在记忆目录内则自动放行
│ ├─ agent/
│ │ └─ AgentLoop.java // 改:最终答复后触发提取;记录本轮是否写过记忆
│ ├─ cli/
│ │ ├─ Renderer.java // 改:渲染"已保存记忆""已补充记忆"提示
│ │ └─ command/
│ │ └─ MemoryCommand.java // 新:/memory 命令
│ └─ MccApplication.java // 改:装配记忆模块、注册 Stage 与命令、下发 memoryDir我们可以把这些改动归成两类。
第一类是一个全新的 memory 包,它只负责长期记忆这一件事,内部四个类各自负责一项:行为说明、记忆目录读取、AGENT.md 读取、轮末提取。
第二类是几处很小的既有代码修改,而且多数位置在前面几个里程碑就已经预告过。
memory 包里的四个角色
这个新包里有四个类。我们先看一下各自的职责,后面几节会逐个展开。
AgentMemory:读人写的项目约定AGENT.md(见 5.3)。AutoMemory:记忆目录的门面,负责保证目录存在、读入MEMORY.md索引(见 5.5)。MemoryPromptText:记忆系统的行为提示词,告诉模型四种类型、什么不该存、怎么两步保存(见 5.6、5.7)。MemoryExtractor:每轮对话结束后的补充提取(见 5.8)。
记忆的写入不在这四个类里。写入由模型调用 Write/Edit 工具完成,不是由框架代码直接写文件。
既有代码的几处修改
除了新包,M5 在既有代码上只有几处小改动。我们先把它们列出来,先建立一个整体印象。
ContextAssembler的组装清单:把MemoryStage放在系统提示词之后、会话历史之前。这正是 1.6 里预告过的记忆加载 Stage。SessionPaths:新增一个memoryDir(projectRoot)方法,复用既有的目录推导逻辑,不需要修改原有方法。ToolContext:新增memoryDir和memoryWritesOnly两个字段,供审批钩子判断"这次写入是不是放在记忆目录内"。ApprovalHook:加一条规则,写入的文件位于记忆目录内就直接放行,不弹卡片。AgentLoop:一轮任务收敛后触发补充提取,并记录"本轮是否写过记忆"供提取做互斥判断。
我们可以看到,控制循环的骨架、工具接口、持久化模块都没有结构性改动。
一次"带记忆的会话"的全过程
我们把一条完整链路串一遍:模型从一次纠正里学到东西,并在下次会话里用上。
会话开始:加载记忆
第一步,启动。 MccApplication 调用 AutoMemory.ensureMemoryDirExists(),保证记忆目录存在。这样模型随时可以直接调用 Write,不需要先执行 mkdir。
第二步,组装上下文。 每一轮请求模型前,ContextAssembler 依次执行各 Stage。轮到 MemoryStage 时,它把三块内容拼成一条系统消息:人写的 AGENT.md 全文、记忆系统行为说明、MEMORY.md 索引全文。
第三步,模型看见索引。 当某条索引和当前任务相关时,模型自己调用 Read 去读那个主题文件的正文。渐进式披露就发生在这里。
会话进行中:主动保存
第四步,判断值得记。 模型在推进任务时判断"这值得记",就按两步保存:先用 Write 新建一个主题文件,再往 MEMORY.md 追加一行索引。
第五步,自动放行。 这两次写入的文件都位于记忆目录内,ApprovalHook 识别到后直接放行,不弹审批卡片。AgentLoop 记下"本轮写过记忆目录"。
一轮结束:补充提取兜底
第六步,轮末提取。 本轮循环结束(模型给出不含工具调用的最终答复)后,AgentLoop 会做一次判断:本轮已经写过记忆就跳过;否则执行一次大模型调用,把这一轮里该记而没记的补上。
下次会话:用上记忆
第七步,再次加载。 下次 mcc 启动,第二步再次加载 MEMORY.md,这次索引里已经有了新记的那一条。模型处理相关任务时读它、据此调整做法,用户不用再纠正第二遍。
整个过程里,记忆的加载集中在 MemoryStage,保存走 Read/Write 并由 ApprovalHook 放行,兜底提取集中在 MemoryExtractor。
5.3 AGENT.md:人写的项目约定(位置与加载)
本篇涉及到的源码列表:
com.minicc.memory.AgentMemory.java
com.minicc.context.MemoryStage.java
这一节我们来讲一下两类长期记忆里比较简单的一类:人写的 AGENT.md。
它的定位很清晰:由人维护、随仓库提交、会话一开始就整份读进上下文。
构建命令、代码风格、接口约定这些需要每次都带上的东西,写在这里最合适。
为什么要有这样一个文件
你每次开新会话,总有一些约定要反复说明:"金额用 BigDecimal""改完运行一下测试""数据访问要走 Repository"。
这些约定是项目层面的,不属于某一次对话,也不该靠人记着每次去说。
我们把它们写进项目目录下的 .mcc/AGENT.md,随代码一起提交,团队每个人、每一次会话就都自动带上了。
熟悉 Claude Code 的同学会发现,这正对应它的 CLAUDE.md。
位置:项目级,外加可选的全局
AGENT.md 有两个位置,一主一辅。
- 项目级:
<项目>/.mcc/AGENT.md,由人维护、随仓库提交。这是主路径。 - 全局级(可选):
~/.mcc/AGENT.md,一份对你所有项目都通用的个人约定。
两个都存在时,全局级排在前面、项目级排在后面。因为项目级更贴近当前项目,放在后面让它更靠近模型最新读到的内容。
加载:只读成文本,不解析
AgentMemory 只做一件事:把这两个文件读成文本,拼好交给 MemoryStage 注入。
它不解析、不校验内容,因为 AGENT.md 本来就是给模型看的自然语言约定,不是结构化配置。
// 源码位置:com.minicc.memory.AgentMemory.java
/** 返回拼好的项目约定文本(全局在前、项目在后);两个文件都没有时返回 Optional.empty()。 */
public Optional<String> load() {
StringBuilder sb = new StringBuilder();
readIfExists(stateDir.resolve(AGENT_FILE)) // 可选的全局约定(~/.mcc/AGENT.md)
.ifPresent(text -> sb.append(text).append("\n\n"));
readIfExists(projectRoot.resolve(".mcc").resolve(AGENT_FILE)) // 项目约定(<项目>/.mcc/AGENT.md)
.ifPresent(sb::append);
String merged = sb.toString().strip();
return merged.isEmpty() ? Optional.empty() : Optional.of(merged);
}逻辑很直接:程序先读取可选的全局文件,再读取项目 .mcc 目录下的 AGENT.md,拼接起来去掉首尾空白。两个文件都没有,方法就返回空,MemoryStage 会据此跳过这一块。
readIfExists 也只是"文件存在且非空就读成文本,否则返回空"。读文件时如果出现异常,也会被捕获并忽略,缺文件不会影响正常流程。
AGENT.md 是什么样
它就是一份普通的约定清单。
# 项目约定
- 数据访问必须经过 Repository,不要在 Service 里直接写 SQL。
- 金额字段使用 BigDecimal。
- 修改代码后要运行 `mvn -q test` 验证。
- 新增的 public 方法要有对应的单元测试。没有固定格式要求,把约定写清楚即可。模型每一轮都会带着这份约定来做决策。
它在上下文里的位置
AGENT.md 由 MemoryStage 注入,排在记忆块的最前面,带一个"# 项目约定(AGENT.md)"的小标题。
// 源码位置:com.minicc.context.MemoryStage.java
// 1) 人写的项目约定 AGENT.md(有才加)。
agentMemory.load().ifPresent(text ->
sb.append("# 项目约定(AGENT.md)\n\n").append(text).append("\n\n"));这一整块记忆上下文又紧跟在系统提示词之后、会话历史之前。
这里做了哪些简化
Claude Code 的 CLAUDE.md 有一整套层级:系统级、用户级、项目级,还有规则目录、@import 导入、排除清单、父目录向上查找等。
mini Claude Code 只做两个文件:项目目录下的 .mcc/AGENT.md,以及可选的全局 ~/.mcc/AGENT.md。
要把"人写的约定每次自动带上"这件事讲清楚,一个文件已经足够。多层级是工程上的细节,我们留给有余力的同学去扩展。
5.4 auto memory:索引 + 主题文件(渐进式披露)
本篇涉及到的源码列表:
com.minicc.memory.AutoMemory.java
com.minicc.context.MemoryStage.java
上一节讲的 AGENT.md 是人写的。这一节开始,我们来讲一下另一类:模型自己写的笔记,也就是 auto memory。
这是 M5 的核心。这一节只讲设计思路,只回答一个问题:为什么要把记忆分成"一个索引 + 一组主题文件",而不是存成一个大文件。
一个大文件的问题
最直接的做法,是把学到的内容都写进一个文件,每次会话开始时整份加载进上下文。
这个做法很快就会出问题。
随着记忆越积越多,这个文件会越来越大,每一轮都整份带上,很快就会占满上下文。
更关键的是,这些记忆里绝大多数和当前任务无关。你现在在改前端样式,却要把"上个月那次数据库迁移的教训"也一起带上,只会浪费上下文。
索引 + 主题文件:分两层
更好的做法是分两层,这也是 Claude Code 采用的思路。
MEMORY.md是索引。它是整个记忆系统的入口,每条记忆在这里只占一行,形如- [标题](主题文件.md) — 一句简短描述。它始终整份加载进上下文,但因为只有索引、所以很短。- 主题文件是正文。像
feedback_testing.md、project_migration.md这样,一个主题一个文件,里面才是真正的内容。它们平时不加载。
模型根据索引里的那句描述,判断某条和当前任务相关时,才自己调用 Read 去读对应的主题文件。
这就是渐进式披露
上面这种先看索引、相关时再读正文的做法,有一个名字:渐进式披露。
常驻在上下文里的只有一份短索引,正文按需读取,这样上下文不会被无关记忆占满。
一个具体的例子
假设记忆目录里已经有了一条集成测试的约定。
MEMORY.md 索引里是这样一行:
- [集成测试约定](feedback_testing.md) — 集成测试不要 mock 数据库主题文件 feedback_testing.md 里才是完整内容:
集成测试必须连真实的数据库,不要 mock。
**Why:** 上季度 mock 的测试通过了,但真实迁移在生产环境失败了。
**How to apply:** 为涉及持久层的功能写测试时,一律连测试库,不要用 mock。你让它写一个普通的工具类测试时,它看到索引这一行和当前任务没关系,就不会去读那个文件。
你让它写一个涉及持久层的集成测试时,它判断这一行相关,才去 Read feedback_testing.md,据此决定连真实库。
我们不做"相关性选择器"
这里有一个值得说明的设计选择。
Claude Code 有一个额外的机制:用一次小模型调用,根据当前问题从索引里自动挑出最相关的几条主题文件注入进来。
mini Claude Code 不做这个选择器。
我们让模型看着 MEMORY.md 索引自己判断、自己 Read。
原因有两点。一是渐进式披露的核心本来就是"模型按需去读",让模型自己判断,和这个设计一致。二是这样省掉了一次额外的模型调用,过程也更直接。
它和后面的 Skills 是同一种思想
"索引 + 按需加载"这个模式后面还会再出现。
后面 M7 的 Skills 用的是同一种做法:先给模型一份技能清单,模型判断某个技能有用时,才去加载它的完整正文。
这个模式在编程 Agent 里会反复出现。下一节我们就把它细化成代码:记忆目录怎么布局、MEMORY.md 怎么加载进上下文。
5.5 自动记忆存储目录 + 加载 MEMORY
本篇涉及到的源码列表:
com.minicc.persistence.SessionPaths.java
com.minicc.memory.AutoMemory.java
com.minicc.context.MemoryStage.java
com.minicc.MccApplication.java
上一节我们讲清楚了"索引 + 主题文件"的思路。这一节我们把它细化成代码。
我们主要讲三件事:自动记忆存储目录放在哪里、MEMORY.md 怎么加载进上下文,以及加载后在上下文里是什么样。
自动记忆存储目录
M4 已经建立了"一个项目一个目录"的组织方式:~/.mcc/projects/<清洗后的项目路径>/。
M5 只在它下面再拼一层 memory/。
- 自动记忆存储目录:
~/.mcc/projects/<项目>/memory/。 - 入口索引:
memory/MEMORY.md。 - 主题文件:
memory/*.md,比如memory/feedback_testing.md。
对应到代码,就是在 M4 的 SessionPaths 里新增一个方法,复用它既有的目录推导逻辑。
// 源码位置:com.minicc.persistence.SessionPaths.java
/** 本项目的自动记忆存储目录:<projectDir>/memory/(M5 的 auto memory 都放这里)。 */
public Path memoryDir(Path projectRoot) {
return projectDir(projectRoot).resolve("memory");
}启动时先把目录创建好
自动记忆存储目录在程序启动时就由 AutoMemory 保证存在。
// 源码位置:com.minicc.memory.AutoMemory.java
/** 启动时创建自动记忆存储目录。已存在则直接返回;失败只打印,留给后续 Write 报错。 */
public void ensureMemoryDirExists() {
try {
Files.createDirectories(memoryDir);
} catch (IOException e) {
System.err.println("创建自动记忆存储目录失败(已忽略,模型写入时会再尝试):" + e.getMessage());
}
}这一步很简单,但有实际作用。
因为目录已经创建好了,我们就能在给模型的行为说明里直接告诉它:"目录已经存在,直接用 Write 写入,不需要执行 mkdir,也不需要检查目录是否存在。"这样就省掉了模型为了创建目录而多花的一个回合。
加载 MEMORY.md:有上限、会截断
MEMORY.md 每轮都整份加载。既然每轮都要带上,我们就要限制它的长度,避免它挤占上下文。
AutoMemory 读它的时候,按行数和字节数双上限来截断:200 行、25KB,先达到哪个上限就停在哪里。
// 源码位置:com.minicc.memory.AutoMemory.java
static final int MAX_INDEX_LINES = 200; // 索引行数上限
static final int MAX_INDEX_BYTES = 25_000; // 索引字节数上限
/** 逐行读入 MEMORY.md,行数或 UTF-8 字节数任一超限就停;超限时在末尾附一句告警。 */
public Optional<String> readMemoryIndex() {
Path index = memoryDir.resolve(INDEX_NAME);
if (!Files.isRegularFile(index)) {
return Optional.empty();
}
try (BufferedReader reader = Files.newBufferedReader(index, StandardCharsets.UTF_8)) {
StringBuilder body = new StringBuilder();
int lines = 0, bytes = 0;
String exceeded = null, line;
while ((line = reader.readLine()) != null) {
int extra = line.getBytes(StandardCharsets.UTF_8).length + (body.isEmpty() ? 0 : 1);
if (lines >= MAX_INDEX_LINES || bytes + extra > MAX_INDEX_BYTES) {
exceeded = limitReason(...); // 记下撞的是行数还是字节
break;
}
// ……把这一行拼进 body,更新 lines/bytes……
}
// 超限时在末尾追加一句告警,提醒模型"把索引保持成一行一条、别把正文写进索引"。
}
}这里有一个实现上的细节值得一提:它是逐行读、边读边算,一旦超限就停,不会把整份索引先全读进内存再截断。
超限时,它会在末尾追加一句告警,大致是:"MEMORY.md 已超过行数/字节上限,只加载了其中一部分。请把索引保持成一行一条,把正文移进主题文件。"
注入上下文后是什么样
前面讲的 AGENT.md、记忆行为说明、MEMORY.md 索引这三块,由 MemoryStage 拼成一条系统消息注入。
// 源码位置:com.minicc.context.MemoryStage.java
@Override
public void contribute(List<Message> messages, Session session) {
StringBuilder sb = new StringBuilder();
// 1) 人写的项目约定 AGENT.md(有才加)。
agentMemory.load().ifPresent(text ->
sb.append("# 项目约定(AGENT.md)\n\n").append(text).append("\n\n"));
// 2) 记忆系统行为说明:四类型、什么不该存、两步保存、何时访问(固定文本)。
sb.append(MemoryPromptText.behavioralGuide(autoMemory.dir())).append("\n\n");
// 3) MEMORY.md 索引(渐进式披露的入口;主题文件由模型看着索引按需 Read)。
autoMemory.readMemoryIndex().ifPresentOrElse(
index -> sb.append("## MEMORY.md\n\n").append(index),
() -> sb.append("## MEMORY.md\n\n你的 MEMORY.md 目前为空。新保存的记忆会出现在这里。"));
messages.add(new SystemMessage(sb.toString())); // 作为一条系统消息注入
}注意第三块的处理:索引为空时也会注入一句"目前为空,新保存的记忆会出现在这里"。
这句话不是可有可无的。它明确告诉模型记忆系统是存在的、现在还空着,模型才知道自己可以往里写东西。
为什么放在这个位置
MemoryStage 紧跟系统提示词、排在会话历史之前,这个位置是有意这样安排的。
一方面,记忆是"稳定的背景知识",和系统提示词一样靠前、每轮基本不变,这样有利于前缀缓存。
另一方面,把它放在会话历史之前,模型在读历史、做决策时,就已经带着项目约定和记忆索引了。
// 源码位置:com.minicc.MccApplication.java
ContextAssembler assembler = new ContextAssembler(List.of(
new SystemPromptStage(SystemPrompt.TEXT),
memoryStage, // M5:紧跟系统提示词
skillStage, // M7:放在记忆之后
new PlanModeStage(), // M8
new CompactionStage(compactionManager) // M6:接管会话历史这一段
));5.6 记忆写入:四种类型 + 什么不该写进记忆
本篇涉及到的源码列表:
com.minicc.context.MemoryStage.java
com.minicc.memory.MemoryPromptText.java
前面几节讲了记忆怎么加载。从这一节开始,我们来讲一下记忆是怎么写进去的。
写记忆不经过新工具,模型用已有的 Write/Edit 直接操作记忆目录里的文件。
要让模型记得准确,并且不要什么都记下来,靠的是 MemoryStage 每轮注入的那段行为说明,也就是 MemoryPromptText。
这一节我们来讲一下其中最核心的两部分:记哪四种类型,以及什么不该记。
长期记忆只分四类
行为说明给模型划定了四种记忆类型。这四类有一个共同点:都刻意只记那些"不能从当前项目状态推出来"的东西。
user:用户是谁。记录用户的角色、目标、职责、知识背景。目的是让模型因人而异地协作,对一位资深工程师和一位初学者的讲法应该不一样。feedback:用户的纠正与肯定。既记"别这么做",也记"这么做对了"。project:进行中的工作背景。目标、计划、事故这类无法从代码或 git 推出来的背景信息。reference:外部系统的入口。比如"流水线缺陷在 Linear 的 INGEST 项目里跟踪"。
我们重点说一下 feedback 和 project 这两类,因为它们的正文有固定结构。
feedback 为什么要"连肯定一起记"
feedback 是最重要的一类,它直接决定了模型在这个项目里的工作方式。
一个很关键的约定是:纠正要记,肯定也要记。
如果只记纠正,会出什么问题?模型会知道越来越多的"别这么做",但不知道"这么做是对的",久而久之就会过于谨慎,连合理的做法也不敢采用。
所以用户确认某个不显然的做法有效时("对,就这样做"),这同样要记下来。
feedback 的正文有一个固定结构:先写规则本身,再写一行 Why:,再写一行 How to apply:。
集成测试必须连真实的数据库,不要 mock。
**Why:** 上季度 mock 的测试通过了,但真实迁移在生产环境失败了。
**How to apply:** 为涉及持久层的功能写测试时,一律连测试库,不要用 mock。为什么要写 Why:?因为知道了原因,模型才能在边界情况下自己判断,而不是机械照搬规则。
project 要把相对日期转成绝对日期
project 类记的是进行中的工作背景,它有一个特别的注意点:相对日期必须转成绝对日期。
用户说"周四之后冻结所有非关键合并",模型不能照抄"周四"。
因为过一阵再读到这条记忆时,"周四"已经没法解读了。它要转写成"2026-03-05 起合并冻结"。
project 的正文结构和 feedback 一样:"事实或决定 → Why: → How to apply:"。
什么不该写进记忆
这一条和"记什么"同样重要。如果不加约束,记忆里会很快积累大量没有长期价值的记录。
行为说明里明确列出了几类不该写的东西。
- 能从当前代码推出来的:代码模式、架构、文件路径、项目结构。读代码就能看到,不需要单独记下来。
- 能从 git 推出来的:改动历史、谁改了什么。
git log/git blame才是权威来源。 - 调试过程或修复配方:修复已经在代码里了,提交信息里也有上下文。
- 已经写在
AGENT.md里的:不要重复。 - 临时的任务状态:进行中的工作、本次会话的上下文。那是待办和会话历史的职责。
即使用户明确要求记录,也要先判断
这里有一条需要单独说明的约束:上面这些排除项,即便用户明确说"把这个记下来"也依然成立。
我们举个例子。用户让模型记一份本周的 PR 列表。
正确的做法不是全部记下,而是反问:"这里面哪一点是意外的、不显然的?"然后只记那一部分。
因为一份 PR 列表本身是活动记录,查 git 就有,把它存成记忆没有意义。真正值得记的,是其中某个"出人意料"的点。
这段说明是怎么给到模型的
以上所有的行为准则,都是 MemoryPromptText 里的固定文本常量。
// 源码位置:com.minicc.memory.MemoryPromptText.java
/** 构造每轮注入上下文的「记忆行为说明」(不含 MEMORY.md 正文——那由 MemoryStage 另行追加)。 */
public static String behavioralGuide(Path memoryDir) {
return """
# 长期记忆(auto memory)
你拥有一个位于 `%s` 的、基于文件的持久化记忆系统。该目录已经存在——请用
Write 工具直接写入(不要运行 mkdir,也不要检查它是否存在)。
……
%s // 四种类型
%s // 什么不该存
%s // 如何两步保存
%s // 什么时候去读
%s""".formatted(memoryDir.toString(), TYPES_SECTION,
WHAT_NOT_TO_SAVE_SECTION, HOW_TO_SAVE_SECTION,
WHEN_TO_ACCESS_SECTION, MEMORY_VS_TASKS_SECTION);
}这段说明每一轮都会由 MemoryStage 注入上下文,所以主 Agent 随时都"知道"该怎么记、该记什么。
同一段文本还会被 5.8 要讲的轮末提取复用,两处共用同一份文本,内容保持一致。
至于"怎么保存"(也就是两步保存)和"写入为什么不需审批自动放行",我们放到下一节一起来讲一下。
5.7 两步保存、写入自动放行、主动保存 vs 兜底提取
本篇涉及到的源码列表:
com.minicc.memory.MemoryPromptText.java
com.minicc.permission.ApprovalHook.java
com.minicc.tool.ToolContext.java
com.minicc.agent.AgentLoop.java
com.minicc.cli.Renderer.java
上一节讲了记哪四种类型、什么不该记。这一节我们来讲一下"怎么保存"。
具体分三部分:保存的两个步骤、写入为什么不弹审批卡片、以及两条写入路径怎么配合。
两步保存:先写主题文件,再加索引
保存一条记忆分成两步,这和 5.4 节讲的"索引 + 主题文件"两层结构是对应的。
第一步,把记忆写进它自己的主题文件,带上 frontmatter。
---
name: 集成测试约定
description: 集成测试必须连真实数据库,不要 mock(用于未来判断相关性,写具体些)
type: feedback
---
集成测试必须连真实的数据库,不要 mock。
**Why:** 上季度 mock 的测试通过了,但真实迁移在生产环境失败了。
**How to apply:** 为涉及持久层的功能写测试时,一律连测试库,不要用 mock。frontmatter 有三个字段:name、description、type。其中 description 要写得具体,因为未来的对话正是靠这句话来判断这条记忆相不相关。
第二步,在 MEMORY.md 里加一行指针,指向刚写的那个主题文件。
- [集成测试约定](feedback_testing.md) — 集成测试不要 mock 数据库MEMORY.md 是索引,不是正文
两步保存里有几条关键约定,都写进了行为说明让模型遵守。
最重要的一条:MEMORY.md 是索引,不是正文。
每条占一行、控制在约 150 字符内、没有 frontmatter,绝不把记忆正文直接写进 MEMORY.md。
其它几条也需要注意:按主题组织而不是按时间;发现旧记忆过时就更新或删除;写新记忆之前先看清单,能更新就不要新建重复的。
记忆写入为什么不弹审批卡片
我们在 M3 做过审批:模型要改文件、执行命令,执行前会弹一张审批卡片等你确认。
但记忆写入是个例外,它不该打扰你。
原因很简单:记忆文件是 Agent 自己的笔记,放在 ~/.mcc 下,不修改你项目里的业务代码。这和 M2 的 TodoWrite 不弹卡片是同一类情况。
所以 M5 在 M3 的 ApprovalHook 上加了一条规则:写操作的目标文件如果位于记忆目录内,就直接放行。
// 源码位置:com.minicc.permission.ApprovalHook.java
// 1) 只读工具无副作用,直接放行。
if (tool.isReadOnly()) {
return Decision.allow();
}
// 2) M5 记忆写入:目标放在记忆目录内 → 这是 Agent 自己的笔记、不修改用户代码,直接放行。
if (isWriteTool(tool) && isUnderMemoryDir(call, ctx)) {
return Decision.allow();
}怎么判断写入是不是放在记忆目录内
判断逻辑很直接:从工具调用里取出 file_path,规范化之后看它是不是在记忆目录之下。
// 源码位置:com.minicc.permission.ApprovalHook.java
private static boolean isUnderMemoryDir(AssistantMessage.ToolCall call, ToolContext ctx) {
Path memoryDir = ctx.memoryDir();
if (memoryDir == null) {
return false; // 未启用记忆
}
String filePath = ToolCallHelper.getString(call, "file_path", "").trim();
if (filePath.isEmpty()) {
return false;
}
Path target = Path.of(filePath);
if (!target.isAbsolute()) {
return false; // 相对路径无法可靠判断归属,交给工具自己报错
}
Path normalizedTarget = target.normalize();
Path normalizedMemory = memoryDir.toAbsolutePath().normalize();
return normalizedTarget.startsWith(normalizedMemory);
}这里的 memoryDir 是通过 ToolContext 带进来的。
写入成功后给人一行回执
记忆写入不弹卡片,用户看不到审批过程。为了让用户知道"它确实记了东西",AgentLoop 在检测到一次成功的记忆写入后,会打印一行调暗的回执。
// 源码位置:com.minicc.agent.AgentLoop.java
// 这次写入放在记忆目录内且成功 → 主 Agent 主动记过了,标记本轮已写、给人一行回执。
if (isMemoryWrite(call, result)) {
wroteMemoryThisTurn = true;
renderer.memorySaved(fileName(call));
}这段逻辑同时做了一件重要的事:把 wroteMemoryThisTurn 置为 true。下一节讲到的互斥判断就靠这个布尔值。
两条写入路径:主动保存 vs 兜底提取
记忆有两条写入路径,互相配合、覆盖不同的情况。
- 主动保存:模型在推进任务时判断"这值得记",当场按两步保存。它的行为说明每轮都在上下文里,所以主 Agent 随时能存。
- 兜底提取:为了防止模型专注于完成任务时漏记,每轮对话结束后再补做一次提取。
这两条路径是互斥的。
本轮主 Agent 已经主动写过记忆(wroteMemoryThisTurn 为 true),轮末就不再提取,避免重复记。
这就是上面那个布尔的用处:它是主动保存和兜底提取之间的开关。
兜底提取具体怎么跑,我们放到下一节详细讲。
5.8 轮末补充提取(触发时机、互斥、受限回合、提示词)
本篇涉及到的源码列表:
com.minicc.agent.AgentLoop.java
com.minicc.memory.MemoryExtractor.java
com.minicc.tool.ToolContext.java
com.minicc.permission.ApprovalHook.java
com.minicc.memory.MemoryPromptText.java
上一节我们讲了主动保存,也提到还有一条兜底路径。这一节我们把这条兜底路径讲清楚。
它叫"每轮结束的补充提取",是整个 M5 里逻辑最复杂的一部分,我们在下面分开说明。
为什么要有这一步
主 Agent 在专注完成一个编码任务时,常常不会同时处理记忆。
它当时要完成的是"把这个 bug 修好""把测试运行通过"。用户中途纠正了它一次,它改完就继续执行,没有把这条纠正存进记忆。
补充提取用来兜底:在一轮任务结束之后,专门回看这一轮的对话,把该记而没记的补上。
触发时机与互斥
触发点在一轮循环收敛的时候,也就是模型给出不含工具调用的最终答复之后。
这时 AgentLoop 调用一次 MemoryExtractor。
// 源码位置:com.minicc.agent.AgentLoop.java
// 2) 没有工具调用 → 这是最终答复,渲染后结束。
if (calls.isEmpty()) {
renderReasoning(assistantMessage);
renderer.finalAnswer(assistantMessage.getText());
// M5:一轮收敛后补做一次提取兜底,本轮若已主动写过记忆,则跳过(互斥,避免重复)。
maybeExtractMemories(session, turnStart, wroteMemoryThisTurn);
return;
}最终答复渲染之前,如果这条 assistant消息带了思维链,我们先调用 renderReasoning 把它显示在终端上。没有思维链就跳过,然后才进入记忆提取。
这里的互斥逻辑就是上一节那个布尔。
// 源码位置:com.minicc.agent.AgentLoop.java
private void maybeExtractMemories(Session session, int turnStart, boolean wroteMemoryThisTurn) {
if (memoryExtractor == null || wroteMemoryThisTurn || isCancelled()) {
return; // 本轮已主动记过、或被取消、或没配提取器 → 不提取
}
List<Message> history = session.history();
// 复制出「本轮对话」交给提取(用户请求 + 中间助手/工具消息 + 最终答复)。
List<Message> turnMessages = new ArrayList<>(history.subList(turnStart, history.size()));
memoryExtractor.extract(session, turnMessages);
}有三种情况会直接跳过:本轮已经主动写过记忆、任务被 Ctrl-C 取消了,或者没有配置提取器。
其中"任务被取消就不提取"是有意为之:取消意味着任务被打断,不是正常收敛,这时提取没有意义。
这里要注意,它只截取"本轮对话"交给提取,用的是本轮开始时记下的 turnStart 到当前的这一段。提取只基于这一轮的内容,不会读取整段历史。
用一个受限的一次性回合来执行
理想的做法,是在一个独立上下文的子 Agent 里执行提取。但 mini Claude Code 的子 Agent 抽象要到后续里程碑才建立。
所以 M5 这里用一个替代方案:一个受限的一次性提取回合。它复用控制循环那套"调用模型 + 调度工具",但加了四条限制。
- 输入:本轮的对话消息,加一条"提取提示词"用户消息。
- 工具:只给 Read / Grep / Glob,以及"仅限记忆目录的 Write/Edit"。
- 边界:很小的步数上限,默认 5 步。
- 隔离:提取回合的消息不写进主会话历史、不落盘,唯一的产出就是记忆目录里的文件。
// 源码位置:com.minicc.memory.MemoryExtractor.java
public void extract(Session session, List<Message> turnMessages) {
String index = autoMemory.readMemoryIndex().orElse("");
int visibleCount = countModelVisible(turnMessages);
String prompt = MemoryPromptText.extractionPrompt(visibleCount, index);
// 输入 = 本轮对话 + 一条提取提示词用户消息。
List<Message> input = new ArrayList<>(turnMessages);
input.add(new UserMessage(prompt));
// 记忆专用上下文:换一套干净工作区,写入只允许放在记忆目录(memoryWritesOnly = true)。
ToolContext memCtx = new ToolContext(
session.workingDir(), new WorkspaceState(), new TodoList(),
config.sandbox(), config.bashTimeoutMs(),
null, // 提取很短,无需取消信号
new PermissionState(), // 不复用会话放行;靠 memoryWritesOnly 约束
autoMemory.dir(),
true); // memoryWritesOnly:只放行记忆目录内的写
// 提取是同步的模型调用,会占住几秒。先打一行提示,避免用户以为程序卡住了。
renderer.memoryExtractionStart();
boolean wroteSomething = runBoundedLoop(input, memCtx);
if (wroteSomething) {
renderer.memoryNote("已从本轮对话补充记忆。");
}
// 只有正常跑完才打收尾行。中途失败走「已跳过」,不会走到这里。
renderer.memoryExtractionEnd();
}提取开始前,终端会先打一行「正在整理记忆…」。这一轮提取正常跑完,再打一行「本轮对话的记忆已经整理完成。」
这是一次同步的模型调用,最多要几秒,而这几秒里 Repl 还没回到输入提示符。先把这段等待说清楚,用户就不会以为程序卡住了。
memoryWritesOnly:提取只能写记忆目录
这里有一个新的开关:memoryWritesOnly。
主 Agent 的记忆写入,是"记忆目录内放行、目录外照旧审批"。
但提取回合是无人值守的,如果模型抽筋,写到记忆目录之外,这个时候,也不能像主Agent那样弹卡片等人审批。
所以提取回合把 memoryWritesOnly 置为 true,审批钩子据此收紧规则:只放行记忆目录内的写,写到别处一律直接拒绝(而不是像主Agent那样弹审批卡片)。
// 源码位置:com.minicc.permission.ApprovalHook.java
// 3) M5 提取回合(memoryWritesOnly):目标没命中「记忆目录内」这一条,
// 说明它在记忆目录之外,提取不该碰用户代码,直接拒绝(不弹卡片,提取无人值守)。
if (ctx.memoryWritesOnly()) {
return Decision.deny("记忆提取回合只能写入记忆目录,不能修改:……");
}受限循环:最多几步,不写回主会话
提取的循环本身是一个精简版的控制循环,最多跑 maxSteps 步。
// 源码位置:com.minicc.memory.MemoryExtractor.java
private boolean runBoundedLoop(List<Message> messages, ToolContext memCtx) {
boolean wrote = false;
for (int step = 0; step < maxSteps; step++) {
AssistantMessage assistant = modelClient.call(messages, memoryRegistry.all());
messages.add(assistant);
List<AssistantMessage.ToolCall> calls = assistant.getToolCalls();
if (calls == null || calls.isEmpty()) {
break; // 提取回合给出不含工具调用的结束回复 → 结束
}
List<ToolResult> results = scheduler.execute(calls, memCtx);
for (int k = 0; k < calls.size(); k++) {
// ……记录有没有成功写过记忆文件……
// 工具结果回填进提取回合自己的消息列表(不进主会话历史)。
messages.add(ToolResponseMessage.builder()
.responses(List.of(
new ToolResponseMessage.ToolResponse(call.id(), call.name(), result.content())))
.build());
}
}
return wrote;
}步数上限设置成 5,是因为一次正常的提取两到四个回合就能完成:先读取几个可能相关的文件,再写进去。设置成 5 步,是为了留一些余量。
关键是这一整段循环用的是自己的 messages 列表,执行结束后就丢弃。它既不进主会话历史,也不落盘,对主流程完全透明。
还有一点:提取是旁路,extract 方法整体包在一个 try-catch 里。任何失败都降级为"这次没提取",不会打断主流程。
失败时终端提示「记忆提取跳过」,也不会打印「本轮对话的记忆已经整理完成。」
提取提示词讲了什么
提取回合拿到的那条提示词,由 MemoryPromptText.extractionPrompt 生成。它主要说明这么几件事。
- 你的身份:你现在是记忆提取子任务,分析上面约 N 条消息来更新记忆。
- 边界:只依据这 N 条消息来更新,不要再 grep 源码、读代码、跑 git 去验证。提取不是调研。
- 高效策略:Edit 要求先 Read 过同一文件,所以先把可能要更新的文件并行全部 Read,再并行全部 Write,别把读写在多个回合里交错。
- 复用的说明:随后附上四种类型、什么不该存、两步保存这三段,和主上下文那份是同一份文本。
- 现有清单:最后把现有的
MEMORY.md索引附上,提醒"先查看索引,能更新就不要新建重复的"。
// 源码位置:com.minicc.memory.MemoryPromptText.java
public static String extractionPrompt(int newMessageCount, String index) {
// ……
return """
你现在作为记忆提取子智能体工作。请分析上文最近约 %d 条消息,并据此更新你的持久化记忆系统。
可用工具:Read、Grep、Glob,以及仅限于记忆目录内路径的 Edit/Write。所有其他写入目标都将被拒绝。
……
你必须只使用最近约 %d 条消息中的内容来更新持久化记忆。不要浪费任何回合去进一步调查或核实……
%s // 现有 MEMORY.md
%s // 四种类型
%s // 什么不该存
%s""".formatted(...); // 两步保存
}把"调研"和"提取"分开,是这段提示词的核心用意。提取只负责把这一轮里已经出现的、值得记的内容写进文件,不负责再去代码里查证。
到这里,主动保存和兜底提取这两条写入路径就都讲完了。下一节我们来讲一下 /memory 命令和配置。
5.9 memory 命令 + 配置
本篇涉及到的源码列表:
com.minicc.cli.command.MemoryCommand.java
default-mcc.yml
前面八节我们把 M5 的核心能力都讲完了:两路记忆的加载、四种类型、两步保存、自动放行、轮末提取。
这一节我们来讲一下 /memory 命令,再把配置梳理一遍。
/memory:查看和编辑记忆文件
记忆文件虽然是模型自己维护的,但人也需要能够查看和修改。
比如你想手动修改一条记忆、删掉一条过时的,或者第一次给项目写 AGENT.md。
/memory 提供的就是这个入口:列出可编辑的记忆文件,你选一个,用外部编辑器打开。
我们还是用 5.1 里那个订单项目来看。你想核对昨天记下的那条"别 mock 数据库",在会话里输入 /memory。
> /memory
选择要查看/编辑的记忆文件:
1. 项目约定 AGENT.md(尚未创建)
2. 记忆索引 MEMORY.md
3. 主题 feedback_testing.md
请选择 [1-3]:3
已用 vim 编辑:~/.mcc/projects/-Users-wangzheng-codecrush/memory/feedback_testing.md命令会先打出一张编号卡片。你输入 3 之后,编辑器会接管当前终端。
这里假设 $EDITOR 是 vim,所以回执里写的是 vim。你修改完保存并退出,才会回到 mcc,终端这时才打印那一行"已用 vim 编辑"。
// 源码位置:com.minicc.cli.command.MemoryCommand.java
@Override
public boolean run(String args) {
List<Entry> files = memoryFiles(); // AGENT.md + MEMORY.md + 各主题文件
if (files.isEmpty()) {
renderer.info("暂无记忆文件。");
return false;
}
List<String> options = new ArrayList<>();
for (Entry e : files) {
options.add(e.label + (Files.exists(e.path) ? "" : "(尚未创建)"));
}
int choice = prompter.select(null, "选择要查看/编辑的记忆文件:", options);
if (choice < 0) {
renderer.info("已取消。");
return false;
}
openInEditor(files.get(choice).path);
return false;
}它复用了前面做审批卡片时用过的编号选择 CardPrompter,不用另造一套交互。
你在"请选择"那一行按 Ctrl-C,select 会返回 -1。终端会打印出"已取消。",当前会话还在。
列出哪些文件
memoryFiles() 把所有能编辑的记忆文件收集成一张清单。
// 源码位置:com.minicc.cli.command.MemoryCommand.java
private List<Entry> memoryFiles() {
List<Entry> entries = new ArrayList<>();
entries.add(new Entry("项目约定 AGENT.md",
projectRoot.resolve(".mcc").resolve(AgentMemory.AGENT_FILE))); // <项目>/.mcc/AGENT.md
Path globalAgent = stateDir.resolve(AgentMemory.AGENT_FILE);
if (Files.exists(globalAgent)) {
entries.add(new Entry("全局约定 ~/.mcc/AGENT.md", globalAgent));
}
Path memoryDir = autoMemory.dir();
entries.add(new Entry("记忆索引 MEMORY.md", memoryDir.resolve(AutoMemory.INDEX_NAME)));
// 各主题文件(memory/*.md,排除 MEMORY.md 本身)。
if (Files.isDirectory(memoryDir)) {
// ……列出目录下的 *.md,排除 MEMORY.md,按名字排序加进清单……
}
return entries;
}清单里有项目 AGENT.md(路径是 <项目>/.mcc/AGENT.md)、存在的话还有全局 AGENT.md、MEMORY.md 索引,以及记忆目录下的各个主题文件。
注意 AGENT.md 和 MEMORY.md 即使还不存在也会列出来,标注"(尚未创建)"。这样你第一次写 AGENT.md 也能从这里进。
你选第 1 项时,程序会先在项目的 .mcc 目录下创建一个空的 AGENT.md(目录还不存在就一并建好),再交给编辑器。第一次写项目约定,也可以从这里进入。
请选择 [1-3]:1
已用 vim 编辑:/Users/wangzheng/codecrush/.mcc/AGENT.md已经有 ~/.mcc/AGENT.md 时,清单会在项目约定后面多一项"全局约定 ~/.mcc/AGENT.md"。这个文件如果不存在,清单里就不列出。
打开编辑器
选中之后,命令会用 $VISUAL 或 $EDITOR 指定的外部编辑器打开。
// 源码位置:com.minicc.cli.command.MemoryCommand.java
private void openInEditor(Path target) {
if (!Files.exists(target)) {
if (target.getParent() != null) {
Files.createDirectories(target.getParent()); // 例如项目下还没有 .mcc 目录
}
Files.writeString(target, "", StandardCharsets.UTF_8); // 首次编辑则建空文件
}
String editor = System.getenv("VISUAL");
if (editor == null || editor.isBlank()) {
editor = System.getenv("EDITOR");
}
if (editor == null || editor.isBlank()) {
renderer.info("未设置 $VISUAL / $EDITOR,请手动打开:" + target);
return;
}
// 继承当前终端的输入输出,让 vim/nano 这类全屏编辑器正常工作;等用户编辑完再返回。
Process process = new ProcessBuilder(editor, target.toString()).inheritIO().start();
int code = process.waitFor();
if (code == 0) {
renderer.info("已用 " + editor + " 编辑:" + target);
}
}如果文件不存在,命令会先把父目录建好(项目里还没有 .mcc 时就会建出来),再创建一个空文件,然后再打开。
这里用 inheritIO() 让编辑器接管当前终端,vim、nano 这类全屏编辑器才能正常工作。你改完保存并退出,进程结束后命令才继续。
编辑器退出码为 0 时,命令会补一行回执。前面选主题文件、选尚未创建的 AGENT.md,看到的"已用 vim 编辑:..."都是这一行,编辑器名字来自 $VISUAL 或 $EDITOR。
如果没有设置这两个环境变量,你选完编号之后,它不会自行选择编辑器,只把路径打印出来。
未设置 $VISUAL / $EDITOR,请手动打开:/Users/wangzheng/codecrush/.mcc/AGENT.md你保存并退出之后,不需要重新打开程序。下一条消息会重新读取 AGENT.md 和 MEMORY.md。主题文件则要等模型下次去读的时候,才会看到你改过的内容。
配置:M5 不新增任何字段
这一节的配置很简单:M5 一个新配置字段都不加。
# 源码位置:default-mcc.yml
model: deepseek-flash
maxSteps: 40
contextLimit: 200000
sandbox: true # M2
bashTimeoutMs: 120000 # M2
stateDir: ~/.mcc # M4:状态根目录(记忆目录就挂在这个根下)长期记忆是 M5 的核心能力,默认一律开启,不设开关。
AGENT.md 存在就加载,auto memory 始终加载 MEMORY.md 并每轮兜底提取。没有哪个场景需要把它关掉。
记忆目录沿用 M4 的 stateDir,就是 ~/.mcc/projects/<项目>/memory/,也不新增路径配置。
本章小结
到这里,M5 就完整了。
我们为 Agent 增加了两路长期记忆:人写的 AGENT.md 和模型维护的 auto memory。
它第一次具备了跨会话的连续性:昨天纠正过它的事,今天新会话里依然记得;项目的约定写进 AGENT.md 后每次自动带上。
实现上也延续了前面的做法。记忆加载是往上下文组装器的管线里加一个 Stage,记忆读写复用已有的 Read/Write,记忆写入放行是审批钩子加一条规则。
整个里程碑几乎全是新增、对既有代码改动极小。这正是前面几个里程碑把扩展点留好之后的回报。
下一章我们进入 M6,解决一个新问题:当上下文快被占满时,怎么自动压缩它。
