4.3 Letta Code：内存优先的编码框架

4.3 Letta Code：内存优先的编码框架

本节摘要："内存优先"是一种应用设计立场：把智能体的记忆结构当作系统的核心设计物，业务逻辑围绕记忆的读写与演化展开。本节对比"提示词优先"与"内存优先"两种编码范式的差异，演示以记忆为中心设计一个应用的完整思路，并给出该立场的适用边界。读完本节，你能判断自己的下一个智能体应用该不该采用这种设计。

从提示词优先到记忆优先

大多数开发者接触智能体的第一反应是"提示词工程"：把系统提示词写得尽可能周全，把历史对话想办法塞进去，业务逻辑围绕"怎么问"展开。这种提示词优先的范式在单轮任务上运转良好，可一旦应用需要长期交互，它的天花板立刻出现——提示词是静态的文本，而用户是动态的人，用不变的文本追逐变化的人，追不上。

内存优先的范式把次序倒了过来：先设计智能体的记忆结构——有哪些记忆块、各放什么、容量多少、谁有权改——再让业务逻辑围绕记忆的读写与演化展开。提示词退居二线，只负责定义行为风格；记忆成为应用的核心数据结构，随交互不断生长。这个范式之所以可行，是因为第 2 章拆过的机械结构已经就位：分层存储给了记忆安身之处，记忆工具给了模型编辑之手，持久化给了状态跨越会话的生命。

两种范式的差异，在代码形态上体现得最直接。提示词优先的应用，核心复杂度堆在"组装提示词"的函数里；内存优先的应用，核心复杂度转移到了"记忆结构设计"上：

from letta_client import Letta

client = Letta(base_url="http://localhost:8283")

# 内存优先的设计：应用的"数据模型"就是这几块记忆
agent = client.agents.create(
    name="study_coach",
    memory_blocks=[
        # persona 只写行为风格，不堆业务知识
        {"label": "persona",
         "value": "你是学习教练。每次对话先回顾学习者的近期目标，再给建议。"
                  "学习者披露新目标或新障碍时，主动更新对应记忆。"},
        # human 块只放"人是谁"的高频事实
        {"label": "human",
         "value": "学习者：在职备考，每晚学习。"},
        # 自定义块承载应用的领域状态：当前学习计划
        {"label": "learning_plan",
         "value": "当前阶段：基础巩固。本周重点：数据结构。"},
        # 自定义块承载长期记录：障碍与突破
        {"label": "learning_journal",
         "value": "（尚未记录）"},
    ],
    model="openai/gpt-4o-mini",
    embedding="openai/text-embedding-3-small",
)
​

注意这段设计的三个决策点：persona 压到两句话——行为风格足够，不塞知识；新增了两个自定义块——应用的领域状态（学习计划）与长期记录（学习日志）各自有明确的席位；每块的内容范式都预先想好——计划块存"当前态"，日志块存"流水账"。这些决策的总和，就是这个应用的记忆架构。

以记忆为中心的应用循环

内存优先的应用，业务循环围绕记忆展开。以学习教练为例，一轮交互在记忆视角下发生了什么：

1. 载入即个性化：上下文组装时，学习计划块与学习者画像自动进入提示词，无需业务代码拼接——"知道他是谁、正在学什么"不费一行逻辑。
2. 对话即采集：学习者说"这周卡在二叉树上"，模型自主判断该更新计划块与日志块，编辑动作由记忆工具完成——数据采集内嵌在对话里，没有独立的表单与接口。
3. 追问即检索：涉及更早的历史（"我上次卡壳是什么时候"），模型对召回与存档发起检索——长期记忆的调用同样无需业务代码中转。
4. 周期即治理：计划完成一阶段，需要把旧计划归档、换入新计划——这类结构性变更可以由业务代码按周期触发（SDK 直接改块），也可以交给模型在对话中提议。

整条循环里，业务代码的存在感集中在循环的边缘（创建、周期治理、界面呈现），中心地带的记忆流转全部交给框架与模型。写惯了增删改查的人初见这种形态会有强烈的不适应——数据逻辑去哪了？答案是：它们被"声明式"地表达在了记忆结构与 persona 策略里，而不是过程式的代码里。

一个小型应用的完整记忆设计

把内存优先的思路走完一个闭环，看"设计"落到纸面是什么样。假设要做"求职陪跑助手"，记忆结构三步定型。第一步列认知需求：需要知道用户是谁（背景、目标）、求职进展到哪（阶段状态）、过程中踩过什么坑（经验记录）。第二步对号入座：前两项是高频事实，分别进 human 块与自定义的 job_search_stage 块；坑记录是低频高价值，写入存档按语义检索。第三步写策略进 persona：何时更新阶段块（用户透露投递、面试、拿offer时）、何时写档案（每次复盘的面经与教训）、什么不记（公司敏感信息不入块）。

三步之后，这个应用的"数据模型"就完成了——没有建表语句、没有接口契约，只有几块记忆与几条策略。业务迭代时（比如新增"薪资谈判"阶段），改的是阶段块的取值约定与 persona 里的一句话，而不是迁移数据库。这种"改设计如改配置"的轻快，正是内存优先范式给开发者的回馈。

这个立场的适用边界

内存优先不是普适真理，它的收益与风险都来自"记忆成为核心数据结构"这一点。适合的场景：应用的价值随交互积累而增长——教练、陪练、助理、长期协作者；个性化是核心竞争力，而个性就藏在记忆里；交互以自然语言为主，对话本身即是数据采集口。不适合的场景：状态需要严格的事务与对账（财务、库存类逻辑——那要用真数据库与真代码，别让模型自由发挥）；业务规则刚性且复杂（合规审批流——记忆的模糊性是负债）；一次性任务（记忆无从积累）。

⚠️ 最需要警惕的误区是"全部押注记忆"：把本该由确定性代码处理的逻辑（计费、权限、审计）也塞给记忆系统，等于把工程纪律外包给了概率模型。健康的架构是双轨的——刚性逻辑走代码，演化状态走记忆，边界画在哪里是架构师的核心判断。

给边界画一条实用的分界线：需要"必须正确"的地方走代码，允许"越来越好"的地方走记忆。 支付金额必须正确，走代码；回复风格可以越来越好，走记忆；权限校验必须正确，走代码；用户偏好可以逐渐精准，走记忆。凡是错一次就有真实代价的，别交给概率；凡是需要时间沉淀才有价值的，别硬编码。这条线画清楚了，内存优先的架构才既灵活又安全。

关于内存优先的常见疑问

问：内存优先是不是意味着不用写业务代码了？ 不是，是写的地方变了。确定性逻辑（权限、计费、审计）照旧是代码；变化在于"个性化与状态"这类曾经靠代码硬凑的部分（会话存储、画像表、偏好同步），现在由记忆结构声明式地承载。代码量确实减少，但省下的工程时间会转移去设计记忆结构——总工作量守恒，重心迁移。

问：记忆结构设计错了能改吗？ 能，且成本远低于改数据库表结构。加一个块、改一个块名、调整容量，都是轻量的在线操作；存量记忆的迁移（把旧块的条目整理进新结构）可以用脚本批量完成。这也是内存优先的一个隐性好处：应用的"数据模型"跟着理解一起进化，不被早期设计锁死。

问：自定义块想加多少个都行吗？ 机制上没有硬限制，工程上要克制。每个块都常驻上下文、每轮都消耗 token，块多了等于自带了一堆"必须付费的关注点"。经验值：核心记忆的块数量保持在个位数，每块职责能用一句话说清——说不清职责的块，就是下一个膨胀源。

本节要点回顾

• 范式对比：提示词优先追着变化的人跑，内存优先让记忆承载变化，业务逻辑围绕记忆读写展开。
• 设计三决策：persona 只写风格、领域状态设自定义块、每块内容范式预先定义——总和即记忆架构。
• 四步循环：载入即个性化、对话即采集、追问即检索、周期即治理，业务代码退守循环边缘。
• 适用边界：价值随积累增长的应用适合；刚性事务与复杂规则必须留在确定性代码里。
• 双轨原则：刚性逻辑走代码、演化状态走记忆，边界判断是内存优先架构的核心功课。

下一节回到程序接口本身：无论是否采纳内存优先的立场，SDK 都是程序观测与操作记忆的标准通道——Python 与 TypeScript 两侧一次讲透。