在本教程中，我们使用 Letta 构建一个有状态的工程 Copilot，用来演示代理式记忆（agentic memory）如何超越传统的基于提示词的对话。我们从可检查的核心记忆块（core memory blocks）入手，这些记忆块可以由 agent 自主更新；随后将这些块暴露出来，以便进行程序化的状态同步，并支持多个 agent 之间共享访问。我们进一步用归档向量记忆（archival vector memory）扩展该架构，以实现语义检索；添加一个自定义的服务端工具，用于确定性的风险估算；使用流式输出观察 agent 的执行过程；利用服务端消息历史实现持久会话；并通过 .af 导出实现可移植性。这些组件共同展示了一种实用的记忆架构，其中持久状态、检索、工具、多 agent 协作和执行轨迹作为一个集成化的代理式系统协同工作。
首先我们安装并初始化 Letta 客户端，然后添加兼容性辅助函数来处理不同 Letta 版本之间的 API 差异。我们用 flex 辅助函数依次尝试多种调用形式，并在全部失败时抛出明确的错误；动态选择可用模型时，优先尝试 openai/gpt-4.1、openai/gpt-4o-mini、anthropic/claude-sonnet-4-20250514，若都不可用则回退到模型列表中的第一个句柄。随后我们创建一个有状态的工程 Copilot，并为其配置结构化的核心记忆块：persona（人格设定，说明我是 Mnemo，一个简洁、具体、绝不编造事实的工程 Copilot，不知道就直说然后去查）、human（关于所合作工程师的持久事实：姓名、角色、技术栈、偏好、工作风格，每当了解到稳定信息时更新）、project_state（正在交付的项目的实时状态：里程碑、阻塞项、决策及其理由，保持密集且最新，删除过时内容）、lessons（来之不易的教训和绝不再犯的错误，仅追加，每行一条）。创建后我们打印 agent 的 id，并导出初始核心记忆，以建立 agent 的持久上下文基线。
接下来演示自我编辑记忆：我们告诉 Copilot「我是 Priya，Northwind 的资深工程师，我们将在 11 月 14 日发布 Halo，一个 Rust 摄取服务。我讨厌冗长的解释——给我要点或代码，不要长篇大论。当前阻塞项：Kafka 消费者在负载下大约每 4 分钟就发生一次再均衡。」随后补充更新：「我们把再均衡追溯到 5 秒的 max.poll.interval.ms 加上缓慢的批量提交。决定：把提交移出轮询循环。另外记住我们已经试过调大 session.timeout.ms，没有效果——不要再建议这个。」两轮对话后我们再次导出核心记忆，观察哪些信息移动到了哪个块中。这展示了 agent 如何自主决定将持久事实写入 human、决策写入 project_state、失败教训写入 lessons。
第三步展示应用程序代码可以直接写入上下文窗口。我们从块中读取当前的 project_state，然后追加一行：「[CI 09:41Z] main 变红：integration/kafka_rebalance_test 失败（已复现不稳定 x3）。」然后问 agent「开始今天工作之前有什么我应该知道的吗？」以验证它能利用外部注入的状态。
第四步演示两个 agent 之间的共享记忆。我们创建一个只读的 policies 块（包含不可协商的工程政策：1. 不允许直接推送到 main；2. 每个修复都必须附带回归测试；3. 客户数据绝不离开欧盟区域），以及一个可读写的 team_scratchpad 块，供 Copilot 和审查者 agent 共享，双方读写时以自己名字为前缀。我们将这两个块附加到 Copilot 上，然后创建 reviewer agent（人格设定为 Argus，一个偏执的资深审查者，专门寻找其他人跳过的失败模式，并按编号引用团队政策），让它共享这两个块。我们让 Copilot 把再均衡问题的拟定修复写入 team_scratchpad（限制 4 行），打印审查者看到的共享块内容，然后让 reviewer 读取并审查该修复、引用其违反的政策，并把裁决追加到同一个块中。最后我们打印审查者回复后的共享块内容，以及附加到该块上的 agent 列表，验证多 agent 之间的持久工作上下文交换。
第五步进入归档记忆：我们批量载入带标签的工程知识，然后用语义搜索检索相关信息，而不依赖精确的关键词匹配。知识条目包括：2024-08-02 的事后复盘（Halo 在部署期间消费者组再均衡时丢失了 120 万事件，根因是轮询循环内的提交阻塞超过了 max.poll.interval.ms）、ADR-017（Halo 使用至少一次投递，基于 (tenant_id, event_id) 的幂等写入；因吞吐量原因拒绝了通过 Kafka 事务实现精确一次）、以及一条运维手册（排空 Halo 节点的方法）。随后我们允许 agent 在回答运维问题时自主查询这些归档知识。
最后我们创建并附加一个自定义的服务端工具 estimate_release_risk，用于确定性的风险估算。该函数接收 open_bugs（P0/P1 未解决缺陷数）、days_to_deadline（距发布日的剩余天数）和 test_coverage（0.0 到 1.0 的覆盖率），通过 pressure = open_bugs / max(days_to_deadline, 1) 计算压力，score = max(0.0, min(100.0, 100 * (1 - exp(-1.4 * pressure)) * (1.3 - test_coverage)))，并给出裁决：低于 35 为 SHIP，低于 70 为 SLIP ONE WEEK，否则为 DO NOT SHIP，返回格式如 risk_score=… verdict=…。我们将该工具 upsert 并附加到 Copilot，打印已附加的工具和 agent 工具列表，然后要求 agent 用「9 个未解决的 P0/P1 缺陷、距 11 月 14 日还有 12 天、覆盖率 0.61」调用该工具评分，并把裁决记录到 project_state 中。
综上，本教程展示了持久状态、检索、工具、多 agent 协作和执行轨迹如何作为集成化的代理式系统协同运作。此外还涉及通过流式输出观察 agent 执行、使用服务端消息历史保持持久会话，以及通过 .af 导出实现可移植的 agent 工作流。需要说明的是，教程中的辅助函数针对多种 API 变体做了兼容处理，因此在实际运行时可能需要根据所用的 Letta 客户端版本调整调用形式；示例中的模型句柄和嵌入模型（openai/text-embedding-3-small）也取决于账户可用性。