letta-ai/letta · 上手攻略

仓库：letta-ai/letta
链接：https://github.com/letta-ai/letta
分类：ai（主分类：agent）
作者：Tom
更新：2026-07-11

这是什么

Letta 是一个面向有状态 Agent 的开发平台，核心特点是让 AI Agent 具备持久记忆——不只是处理当前对话，还能记住之前讨论的内容、积累用户偏好、持续自我进化。

传统 LLM 对话是「失忆」的：每次新建对话，模型不知道你是谁、上次讨论了什么。Letta 的解法是给 Agent 挂上一层结构化的记忆系统（Memory Block），让 Agent 像人一样形成长期记忆。

⚠️ 注意：本仓库（letta-ai/letta）是 Letta 的legacy API 服务器。活跃开发已迁移到 letta-ai/letta-code（Letta Agent CLI / Desktop App）；自托管 API 服务器请使用 App Server。本文兼顾 legacy SDK 和新版 Agent SDK 使用方式。

解决什么问题

Agent 记忆缺失：每次对话都得重新交代背景 → Letta 给 Agent 持久化记忆，下次对话直接记住
个人 AI 助手体验割裂：每次新建对话就要重新介绍自己 → Agent 有「自我认知」，持续学习用户偏好
无法追踪历史：用 ChatGPT 讨论过的技术方案，找不回来了 → Letta 可搜索全部历史对话
缺乏结构化上下文：Prompt 里塞一堆 System Prompt 又乱又短 → Letta 用 Memory Block 组织信息（事实、偏好、技能等）
多 Agent 协作：需要一个 Agent 能 spawn 子 Agent → Letta 支持 Subagent

快速安装

方式一：桌面 App（最简，推荐尝鲜）

下载 Letta Agent 桌面版：https://lettal.com/download
安装后打开，注册账号
连接 Model Provider（填入 OpenAI / Anthropic / zAI 等 API Key）
开始与 Agent 对话

方式二：CLI（Letta Code）

需要 Node.js 22.19+：

npm install -g @letta-ai/letta-code
letta                    # 启动交互式 Agent
letta -p "query"         # 无头模式执行单条指令

方式三：在自己的应用里集成（Letta Agent SDK）

npm install @letta-ai/letta-agent-sdk

import { LettaAgentClient } from "@letta-ai/letta-agent-sdk";

const client = new LettaAgentClient({
  backend: "cloud",          // 或 "local"（完全本地运行）
  apiKey: process.env.LETTA_API_KEY,
});

// 创建 Agent
const agentId = await client.createAgent({
  model: "anthropic/claude-opus-4-8",
  persona: "I am Nora, a proactive digital chief of staff.",
  human: "The user prefers concise summaries with risks and evidence.",
});

// 发送消息并流式获取回复
await using session = client.resumeSession(agentId);
await session.send("What do you know about me?");
for await (const message of session.stream()) {
  if (message.type === "assistant") console.log(message.content);
}

完全本地运行（不调用任何外部 API，数据不出机器）：

const client = new LettaAgentClient({ backend: "local" });

核心用法

1. Memory Block 系统

Letta Agent 的记忆以「块」（Block）为单位组织，常见类型：

Block 类型	用途
`persona`	Agent 的自我认知（我是谁，我的性格）
`human`	用户信息（用户是谁，有什么偏好）
`custom`	任意自定义记忆块

2. 关键命令（Letta Code CLI）

命令	功能
`letta`	启动交互式 Agent
`letta -p "指令"`	无头模式执行
`/init`	深度记忆初始化
`/remember xxx`	教导 Agent 记住某事
`/memory`	查看/管理当前记忆块
`/search xxx`	搜索历史消息
`/model`	切换 LLM 模型
`letta --new`	新建对话（共享 Agent 记忆）
`Shift+Tab`	切换权限模式

3. Skills（技能扩展）

Letta Agent 支持自定义 Skills（类似 OpenClaw 的 Skills 概念），以模块化方式扩展 Agent 能力：

# 查看内置 skills
# 参考：https://docs.letta.com/letta-agent/skills

4. Subagent（子 Agent）

Letta Agent 可以 spawn 子 Agent 处理特定任务，子 Agent 之间可协作：

主 Agent (Nora)
  ├── 子 Agent A → 专门负责代码审查
  ├── 子 Agent B → 专门负责文献检索
  └── 子 Agent C → 专门负责日程管理

5. Scheduling（定时任务）

让 Agent 在特定时间自动执行任务（如「每天早上 9 点给我发一份当日待办」）。

6. 自托管 App Server

如果想自建 API 服务器而不是用 Letta Cloud：

# 参考：https://docs.letta.com/letta-agent/app-server

典型适用场景

场景	价值
个人 AI OS 伴侣	跨对话记住你的工作背景、偏好、正在做的项目
编程助手	能记住你项目的代码风格、已有架构，持续改进建议
研究助理	追踪你读过的论文、形成的观点，支持多轮深入讨论
客服/销售 Agent	记住用户历史交互，提供个性化服务
多 Agent 协作系统	一个主 Agent 协调多个专业子 Agent 分工

坑与注意

仓库结构复杂：letta-ai/letta 本身是 legacy API 服务器，实际 CLI 和 App 开发已迁移到 letta-ai/letta-code。看文档/Issue 时注意区分是哪个仓库。
Node.js 版本要求：Letta Code CLI 需要 Node.js ≥ 22.19，旧版 Node 会报错。
API Key 安全：使用 Letta Cloud 时 API Key 会暴露给前端，敏感场景建议用 backend: "local" 完全本地运行。
记忆质量依赖对话质量：Agent 记忆的构建依赖你如何与它互动（是否主动用 /remember 纠正、是否用 /init 初始化），不干预则记忆可能不准确或产生幻觉。
v1 SDK vs Agent SDK：Letta 存在两代 SDK——v1（@letta-ai/letta-client / letta-client Python）面向 legacy API server；新项目请用 Agent SDK（@letta-ai/letta-agent-sdk）。
中文资料少：Letta 社区以英文为主，中文文档和视频教程都比较匮乏。

与同类对比

方案	优势	劣势
Letta	Memory Block 结构化、Subagent 协作、Cloud+本地双模式	相对新，生态不如 LangChain Agents 成熟
ChatGPT Memory	直接用，体验简单	记忆粒度粗，无 Subagent，不开源
LangChain Agents	生态最大，工具最全	记忆机制薄弱，需自己搭
AutoGPT	自主规划能力强	记忆管理同样粗糙，更偏实验性
MemGPT	记忆层次设计好（主上下文 + 历史）	工具生态弱，专注记忆而非全栈 Agent
G hose	偏代码任务，subagent 协作	记忆系统不如 Letta 结构化

结论：如果你需要的是「一个有长期记忆、能持续学习用户偏好的 AI 助手」，Letta 是目前开源方案里做得最完整的——Memory Block + Subagent + Cloud/本地双模式，比自搭 LangChain Agent 省大量功夫。

一句话推荐

想让 AI 真正「认识你」而不是每次对话都从零开始？Letta 把持久记忆变成了第一等公民——Memory Block 结构化积累、Subagent 协作分工、本地/云端自由切换，做个人 AI OS 的开源首选。