Letta Code：长期记忆为什么不等于当前上下文
可编辑图源 · PNG 预览 · 图的文字版
本篇核对的是
letta-ai/letta-code在1f55d3dc66e238d203757fae288bb53f3adc7cd3的源码与内置提示。图中特意选择 local MemFS v1；Letta Code 还有 API-backed MemFS v2 和非 MemFS 模式，不能把这张图当成所有部署的完整拓扑。证据等级是静态源码及内置提示核对，未做启动后的运行追踪或跨设备同步验证。
先回答一个问题
Agent 把东西“记住”了，究竟是写入了本轮模型可见的提示、存入可检索的文件，还是留在对话历史里？Letta Code 把这些位置分开：核心记忆块在提示中；外部文件和 Skills 通常要按需读取；历史消息由 recall 路径查找。MemFS 的文件修改与已编译的当前回合提示不是同一事件；后续何时可见还取决于具体写入、同步与重编译路径。这个区分比一句“拥有长期记忆”更能解释系统行为。
三个问题，三个位置
| 问题 | 本篇 local MemFS v1 中的位置 | 模型何时看见 |
|---|---|---|
| 每轮都应知道的身份、偏好、索引 | system/ 下的核心记忆 Markdown，映射为 memory blocks | 编入 system prompt；有上下文成本 |
| 详细参考资料与程序化做法 | MemFS 外部 Markdown / Skills | 可由路径或描述帮助发现；正文通过文件/工具按需读取，不默认完整内联 |
| 过去对话里发生过什么 | conversation history / recall | 当前窗口保留近期消息和旧消息摘要；更早细节需检索 |
这张表描述的是内置提示里的设计及对应代码路径，不证明所有模型都遵循“按需读取”的建议，也不证明 recall 的实际命中率。内置 local MemFS 提示：历史与三类记忆
关键代码如何串起来
detectMemoryFormat(memoryDir, localMemfs)：本地 MemFS 返回 v1；非本地且有根MEMORY.md才识别为 v2。isCoreMemoryPath因此在 v1 判断system/，在 v2 判断根目录 Markdown。源码estimateSystemPromptSize用同一个格式判断核心记忆的范围：v1 递归统计system/，v2 统计根目录 Markdown。这里是 4 字节 / token 的粗估，不是模型计费或真实 token 数。源码memory()工具解析目标目录、核对工作树、执行编辑，并调用commitMemoryWrite提交受影响路径；这解释了“写文件”和“持久化”之间还有一步。工具实现 · Git 提交实现- 对于 memory worker 的合并路径，代码先处理同步，再在能力允许时请求
recompileAgentSystemPrompt；内置提示也写明当前回合不会因编辑而立刻改变已编译提示。不能据此泛化为所有工具写入都在同一时机重编译。worker 路径 · 重编译入口
v1 与 v2 不要混成一张目录图
当前代码同时保留几种运行配置。API-backed v2 用根 MEMORY.md 作为索引标记，核心记忆在根目录 Markdown；local MemFS 则仍按 v1 的 system/ 识别。v2 子目录还有逐级 MEMORY.md 索引要求。这是源码分支，不是“老版本已全部淘汰”或“所有部署都已切 v2”。格式判定与索引约束 · 创建 Agent 时根块的用途
易误解的地方
- “存到磁盘 = 下一 token 就会记得”：错误。当前回合使用已经装载的提示；文件写入、Git 提交、同步、提示重编译是不同事件。
- “所有长期信息都塞在 system prompt”：错误。详细文件和 Skills 是外部记忆；核心块要克制，内置提示也建议把可重新查到的细节移出去。
- “Recall 与 memory block 是一回事”：错误。前者查历史经验，后者承载可维护的当前核心记忆。
- “这张图证明记忆有效”：错误。图只说明所选源码路径的状态分层；准确性、召回率、跨会话持久性仍需实验。
下一步核验
在隔离测试 Agent 上分别写入核心块、外部文件和对话事实，记录下一轮的提示重编译结果、实际可见内容、recall 调用与 Git revision；然后对 API-backed v2 重做同样实验。不能用静态阅读替代这些结果。
图的文字说明 · letta-memory
本图回答“记忆存放的位置与当前上下文是什么关系”，不是 Letta 所有后端的完整架构图。源码固定于 letta-ai/letta-code@1f55d3dc。回到章节
- 左栏分列三种存放处：local MemFS v1 将
system/下任意深度的 Markdown 识别为核心记忆块，包括子目录中的文件；这些块可承载身份、偏好、索引等内容。外部文件和 Skills 按需通过工具读取；对话历史与 recall 另列，不等同于这两类 Markdown。 - 三条箭头指向本轮上下文的不同位置：核心块默认编入 system prompt；外部文件经工具读取后，内容成为本轮 conversation 的一部分，并非默认内联在 system prompt；近期对话和较早消息摘要在当前 conversation 中，更早信息可经 recall 检索。箭头表达设计中的可见路径，不表示每次都发生读取或检索。
- 底部并列两条已读到的源码路径：
memory()工具写入后调用commitMemoryWrite；memory worker 合并时先同步，再在能力允许时重编译提示。它们不是一条所有写入必经的流水线；已编译的当前回合提示也不会被文件编辑即时改写。
图中箭头表示设计路径，不是实测调用轨迹。绿色箭头不表示外部文件默认完整加载进 system prompt。API-backed MemFS v2 把核心文件放在根目录，并以 MEMORY.md 组织索引；本图不描述该布局。格式分支源码
编辑 build.py 后运行 python3 figures/letta-memory/build.py，再用仓库说明的 Excalidraw renderer 从 scene.excalidraw 导出 diagram.svg 与 preview.png。交互式 MCP 画布可能更换字体，仓库导出图才是发布视觉基准。
在线预览稿：书稿仍在校稿，系统篇以文内固定源码版本为准；静态阅读不等于运行验收。