letta 学习页

letta 把 agent 的核心块记忆、会话消息、归档记忆和 Git-backed 存储串成一条可重建的上下文链。

它最有代表性的地方是把 prompt 内可见的 core memory、会话消息、归档检索记忆和 Git-backed block 统一到同一平台模型里，但这几层仍然有清楚边界。

源码事实平台型 Agent 系统

回横向对照打开证据页

这页怎么读

先看“这一轮模型看到了什么”，建立模型视角。
再看 context 和 memory 两张图，抓主链。
最后看源码锚点和证据页，确认细节。

这一轮模型到底看到了什么

这一段只讲模型真正可见的材料，不把所有底层状态都算进 context。

context 组成图

letta 先编译 memory，再把它固化成会话的 system message，然后才去计算当前窗口。

AgentState

总状态容器。

Memory.compile

把块记忆渲染成模型可读文本。

PromptGenerator

补上 agent / conversation 元信息。

system message

作为会话第 0 条消息固定下来。

ContextWindowCalculator

再评估窗口预算。

Summarizer

窗口过大时插入 summary message。

模型先看到被编译好的 system prompt，其中包含 CORE_MEMORY、工具规则、来源目录和记忆元信息。
标准模式下，核心记忆以 <memory_blocks> 呈现，带有 human、persona 等块、描述、字符上限和只读标记。
Git 模式下，记忆会变成 <memory_filesystem> / <memory> / <self> 的路径化文件树，而不是平铺块。
对话历史不是原始全量 transcript，窗口里只保留 system message、必要消息，以及可能插入的 summary message。
available_skills 只在请求构建时注入，不会被长期持久化进 system prompt 存储。
归档记忆通常不直接塞进 prompt，本体靠检索工具取回，模型先看到的是数量、标签和元信息。

context 是怎么拼起来的

先看组成块，再看顺序。这里最容易帮助普通读者分清“哪些东西会真的进模型”。

AgentState

agent 的总状态容器，承载 system、memory、blocks、sources、tools、message_ids 和 compaction_settings。

状态容器

Memory.compile

把 memory blocks、tool rules、sources 和文件块渲染成 LLM 可读的上下文文本。

上下文渲染

PromptGenerator metadata

为 system prompt 追加 AGENT_ID、CONVERSATION_ID、消息数和归档规模。

提示注入

Conversation system message

每个 conversation 都有自己持久化的 system message，位置 0，由当前 memory 重新编译得到。

会话固化

ContextWindowCalculator

按 token 预算拆出 system、memory、summary、messages、tools 等部分。

窗口评估

Git / Archive storage

核心块和归档记忆分别走 git-backed blocks、SQL passages 和可选向量库检索。

持久化与检索

创建或更新 agent 时，先整理 memory_blocks、tags、sources 和 compaction_settings。
需要 Git-backed memory 时，把块标签转成路径化标签，再创建或回填 memfs repo。
PromptGenerator.compile_system_message_async() 调 Memory.compile()，把核心记忆、工具规则和来源目录装进 system prompt。
ConversationManager 把这份 system message 持久化为 conversation 的第 0 条消息，并写入 conversation_messages。
ContextWindowCalculator 再把 system、memory、files、summary、messages 和 tools 拆开计 token，判断当前窗口占用。
一旦窗口压力过大，Summarizer 会压缩旧消息，插入 summary message，再继续后续轮次。

memory 是怎么形成、保存、再被取回的

不要把记忆想成一个抽象黑盒。这里直接按时间顺序讲“它什么时候生成、存哪、怎么再回来”。

memory 流程时间线

核心块记忆、Git-backed 持久化和 archive 检索并不是一条线，而是在重编译点相互联动。

Block 创建/更新

先改核心块。

Git serialize

Git 模式下写成 Markdown + frontmatter。

Postgres cache

同步缓存当前状态。

System prompt rebuild

重编译 core memory。

Conversation message 0

更新会话里的 system message。

Archive search

长期记忆走工具检索返回。

块先以 label/value/limit/read_only/description/metadata 的形式存在，默认核心块是 human 和 persona。
Git 模式下，块会被序列化成 Markdown + YAML frontmatter，落到 ~/.letta/memfs/{org_id}/{agent_id}/repo.git。
写入流程是 git 先行、Postgres 缓存随后同步；启用 Git-backed memory 时还支持 repo 缺失回填。
记忆块变更后，系统会重编译 prompt，并重写 conversation 的 system message。
运行时新增长期记忆会进入 archive/passage：先写 SQL，再按需双写到向量后端。
检索时根据 embedding、标签和时间范围搜索归档记忆，把结果作为工具返回给模型。

存储分层图

很多误解都来自把 transcript、summary、文件、数据库和向量库混成一层看。

存储分层图

prompt 可见层、会话层、Git 真源层、缓存层和归档层都不同。

Memory.blocks

prompt 可见的核心块记忆。

conversation_messages

当前会话的 system 和消息顺序。

memfs repo

Git-backed block 的版本真源。

Postgres

快速读写与同步缓存。

Archive SQL

长期归档记忆主体。

Vector DB

语义检索层。

记忆块层：Memory.blocks / Block，负责模型当前可见的核心记忆。
会话层：messages + conversation_messages，负责当前 conversation 的消息顺序和 system message 归属。
Git 层：memfs repo 和 Markdown 文件，负责 Git-backed block 的版本历史。
缓存层：PostgreSQL，负责快速读写和与 git 状态同步。
归档层：Archive / Passage 的 SQL 存储，负责长期记忆主体。
向量层：可选 Turbopuffer / embedding 检索，负责归档记忆的语义搜索。