AI 换个会话就装失忆？Letta 焊死「记忆即灵魂」，从 MemGPT 的 OS 梦到 Core/Recall/Archival 三层记忆一篇打通

帅哥的AI自修课2026-08-27 19:12

AI 换个会话就装失忆？Letta 焊死「记忆即灵魂」，从 MemGPT 的 OS 梦到 Core/Recall/Archival 三层记忆一篇打通

版本说明 ：本文基于 Letta V1 SDK （letta-client，Python，本文撰写时）编写。Letta 由 MemGPT 快速演进而来，0.5.x 时代的 create_client() / send_message() / insert_archival_memory() 等接口已在 0.6.0+ 移除。本文统一使用 V1 SDK（from letta_client import Letta）。Letta 仍在快速迭代，具体 API 与参数请以官方最新文档为准：https://docs.letta.com
免责声明：本文为第三方学习整理，不属于 Letta 官方文档。框架迭代速度快，文中所有代码、API 仅供学习参考，生产使用请务必查阅官方文档；因版本变更导致的问题，本文不承担责任。

版权与来源声明 ：文中所有代码仅用于学习演示，不构成生产实施建议；所有 API 以项目官方 GitHub 与官方文档为准；开源项目的商标、项目名称归各项目官方所有。
⚠️ 提示：Agno、Letta 更新迭代非常快，复制代码前优先核对官方最新示例，部分参数 / 方法名可能已经变更。
当大多数 Agent 框架还在追逐"无状态即简单"时，Letta 反其道而行------它把记忆当作 Agent 的灵魂。本文将从核心理念到生产部署，带你系统掌握这个有状态 Agent 框架。

一、项目简介

1.1 什么是 Letta

Letta（前身为 MemGPT）是一个有状态（stateful）的 LLM Agent 框架，核心思想是将大语言模型类比为计算机的 CPU，而外部存储类比为内存和硬盘。通过精心设计的记忆层级架构，Letta 让 Agent 能够在长对话、复杂任务中保持连贯的上下文，而不会因为 token 限制而"失忆"。

1.2 项目背景与历史

Letta 起源于 2023 年 UC Berkeley 的研究项目 MemGPT（Memory-GPT） ，由 Charles Packer、Sarah Wooders 等人发起。MemGPT 的论文《MemGPT: Towards LLMs as Operating Systems》提出了一个开创性的观点：如果把 LLM 看作操作系统的 CPU，那么上下文窗口就是 RAM，而外部存储就是硬盘。通过类似虚拟内存的分页机制，Agent 可以在有限的上下文窗口中管理无限的记忆。

2024 年 9 月 23 日，MemGPT 正式更名为 Letta（公司走出 stealth，完成 1000 万美元种子轮），并从研究项目转型为生产级框架，推出了 Letta Server、Python SDK、REST API 等完整工具链。Letta 已迭代到 0.16.x，并发布了 1.0 SDK。

1.3 核心特性

特性 说明
分层记忆架构 Core Memory + Recall Memory + Archival Memory 三级存储
有状态 Agent Agent 状态持久化，支持跨会话恢复
自我反思机制 Agent 自动管理记忆，包括总结、压缩、归档
工具系统 支持内置与自定义工具，与记忆系统深度集成
多 Agent 协作 内置多 Agent 通信机制
数据源集成 支持连接外部数据源实现 RAG
REST API 服务 完整的服务端部署方案
Python SDK 简洁的客户端编程接口（V1 SDK：letta-client）

1.4 架构概览

Letta 的整体架构分为三层：

复制代码 
┌─────────────────────────────────────────┐
│              Client Layer                │
│  Python SDK / REST API / Web UI         │
├─────────────────────────────────────────┤
│              Server Layer                │
│  Agent Manager / Memory Manager          │
│  Tool Executor / Message Router          │
├─────────────────────────────────────────┤
│            Storage Layer                 │
│  PostgreSQL(Metadata) / Vector DB        │
│  (Archival) / SQLite(Default)            │
└─────────────────────────────────────────┘

二、核心理念与设计哲学

2.1 操作系统类比

Letta 最核心的设计隐喻是操作系统：

操作系统概念 Letta 对应 作用
CPU LLM 执行推理、生成响应
RAM（主存） Context Window 当前可访问的上下文
虚拟内存 Memory Paging 在有限上下文中管理大量记忆
硬盘 Archival Memory 长期持久化存储
进程 Agent 独立的执行单元，拥有自己的状态
系统调用 Tool Calls Agent 与外部世界交互的接口
中断 Message 触发 Agent 执行的事件

这个类比不是噱头，它直接决定了 Letta 的架构设计。就像操作系统通过虚拟内存让进程"以为"自己拥有无限内存一样，Letta 通过记忆分页让 Agent"以为"自己拥有无限上下文。

2.2 核心设计原则

原则一：记忆是一等公民。 在大多数框架中，记忆是附加功能；在 Letta 中，记忆是核心架构。Agent 的每一次思考、每一次工具调用、每一次回复，都围绕记忆管理展开。

原则二：有状态优于无状态。 无状态 Agent 简单但脆弱------每次对话都要重新理解用户。Letta 坚持有状态设计，Agent 的记忆、配置、工具绑定都持久化存储，跨会话保持一致。

原则三：自我管理优于人工管理。 Letta 的 Agent 具备自我反思能力，能够自动判断哪些信息该存入 Core Memory、哪些该归档、哪些该遗忘。开发者不需要手动管理记忆。

原则四：工具即能力。 Letta 的工具系统与记忆系统深度集成，工具不仅能执行外部操作，还能读写记忆。这种设计让 Agent 的能力扩展自然且一致。

2.3 为什么需要有状态 Agent

想象一个客户支持场景：用户第一天反映了一个问题，客服记录了用户的设备信息、问题描述和临时解决方案。第二天用户回来跟进，无状态 Agent 需要用户重新描述一切，而有状态 Agent 能直接调出昨天的记忆继续处理。

这就是有状态 Agent 的价值------它让交互具有连续性，让 AI 真正"认识"你。

在实际应用中，有状态 Agent 的优势体现在：

  • 长对话不丢失上下文：即使对话超过模型的上下文窗口，关键信息仍被保留在记忆中
  • 跨会话一致性：用户的偏好、历史行为、之前的决策都能被记住
  • 复杂任务追踪：多步骤任务的中间状态可以持久化，支持中断恢复
  • 个性化体验：基于长期记忆提供定制化的服务

三、核心概念

3.1 记忆层级架构

Letta 的记忆系统分为三个层级，形成一个金字塔结构：

复制代码 
        ┌──────────────┐
        │  Core Memory │  ← 高频访问，常驻上下文
        │  (核心记忆)   │
        ├──────────────┤
        │ Recall Memory│  ← 对话历史，按需检索
        │  (回忆记忆)   │
        ├──────────────┤
        │Archival Memory│ ← 长期存储，向量检索
        │  (档案记忆)   │
        └──────────────┘

3.2 核心记忆（Core Memory）

Core Memory 是 Agent 最重要的记忆，始终驻留在 LLM 的上下文窗口中 。新版 SDK 中它由一组 Memory Block 承载，每个 Block 有 label（如 persona / human）、value（内容）和 limit（字符上限）。

  • Persona（人格）：定义 Agent 的身份、性格、行为准则。例如"你是一个专业的Python编程助手，擅长代码审查和性能优化"。
  • Human（用户画像）：存储关于用户的关键信息。例如"用户是一名后端开发者，使用Python和Go，偏好简洁的代码风格"。

Core Memory 的特点是小而精 ，通常只包含几百到几千个 token。Agent 可以自动改写这些 Block（例如把用户姓名写入 human Block）。

3.3 回忆记忆（Recall Memory）

Recall Memory 是 Agent 的完整对话历史，包括所有用户消息、助手回复、工具调用和结果。它存储在数据库中，当需要时通过搜索检索相关历史片段放入上下文。

Recall Memory 的检索方式：

  • 时间窗口检索：取最近的 N 条消息
  • 语义检索：根据当前查询的语义相似度检索相关历史消息
  • 混合检索：结合时间和语义

3.4 档案记忆（Archival Memory）

Archival Memory 是 Agent 的长期知识库，用于存储大量结构化或非结构化信息。它基于向量数据库实现，支持语义搜索。

典型使用场景：

  • 存储项目文档、技术规范
  • 存储用户上传的文件内容
  • 存储 Agent 在执行任务中收集的知识
  • 存储外部数据源的检索结果

在 V1 SDK 中，写入档案用 client.agents.passages.create(agent_id, text=...)，检索通常交给 Agent 在对话中自动完成（Agent 内部调用 archival 检索工具）。

3.5 工具函数（Function）

在 Letta 中，工具是 Agent 与外部世界交互的方式。内置工具（如 web_search、run_code）通过名称直接引用；自定义工具通过 client.tools 注册（详见官方工具文档）。记忆操作本身也是通过工具实现的------Agent 会自动调用 core_memory_append / core_memory_replace / archival_memory_search 等来管理自己的记忆。

⚠️ 安全提示 ：内置的 run_code 工具会在服务端执行代码，存在安全风险。任何对外暴露的服务务必做沙箱隔离（容器 / 受限用户 / 网络隔离），禁止以高权限身份运行。

3.6 Agent 生命周期

一个 Letta Agent 的完整生命周期：

复制代码 
创建 → 初始化记忆 → 接收消息 → 推理思考 → 调用工具 → 更新记忆 → 生成回复 → (循环) → 终止

关键阶段说明：

  • 创建：指定 Agent 配置（模型、记忆 Block、工具集）
  • 初始化：加载 Persona 和 Human 到 Core Memory（即 Memory Block）
  • 消息循环：接收消息 → LLM 推理 → 可能多次工具调用 → 最终回复
  • 自我反思：在特定时机（如对话过长、记忆满）触发记忆整理
  • 持久化：Agent 状态自动保存到数据库，支持随时恢复

四、安装与环境配置

4.1 安装 Letta

Python 侧使用 V1 SDK （letta-client）：

bash 复制代码 
# Python SDK（编写代码用）
pip install letta-client

# 自托管服务端（如需本地/服务器运行 Letta Server）
pip install letta

注意：老教程里的 pip install letta + from letta import create_client 属于 0.5.x 时代 API，已在 0.6.0+ 移除。新项目请统一使用 letta-client。

4.2 启动服务端（自托管）

bash 复制代码 
# 本地启动 Letta Server（默认端口 8283）
letta server

# 或指定端口
letta server --port 9000

4.3 环境变量

Letta 通过环境变量配置关键参数（以 OpenAI 为例）：

bash 复制代码 
# LLM 配置（V1 SDK 用模型 handle，如 openai/gpt-4.1）
export OPENAI_API_KEY=sk-your-key

# 嵌入模型（用于 Archival Memory / 数据源的向量化）
export OPENAI_API_KEY=sk-your-key

# 自托管服务端连接地址（如使用 Cloud 则改用 LETTA_API_KEY）
export LETTA_BASE_URL=http://localhost:8283

4.4 依赖架构

Letta 的核心依赖：

组件 用途 默认 可选
数据库 元数据存储 SQLite PostgreSQL
向量数据库 Archival Memory SQLite + sqlite-vec pgvector / Qdrant / Chroma
LLM Provider 推理引擎 OpenAI Anthropic / Groq / Ollama / Azure
Embedding Provider 向量嵌入 OpenAI Ollama / HuggingFace

4.5 Docker 部署（自托管）

生产环境推荐使用 Docker 一键部署：

yaml 复制代码 
version: "3.8"
services:
  letta:
    image: letta/letta:latest
    ports:
      - "8283:8283"
    environment:
      - OPENAI_API_KEY=${OPENAI_API_KEY}
      - LETTA_BASE_URL=http://localhost:8283
    volumes:
      - letta-data:/app/data

  postgres:
    image: pgvector/pgvector:pg16
    environment:
      - POSTGRES_USER=letta
      - POSTGRES_PASSWORD=letta
      - POSTGRES_DB=letta
    volumes:
      - pgdata:/var/lib/postgresql/data

volumes:
  letta-data:
  pgdata:

说明：新版的配置项已从旧的 LETTA_LLM_MODEL_BACKEND / LETTA_EMBEDDING_MODEL 等精简为以模型 handle 字符串（如 openai/gpt-4.1、openai/text-embedding-3-small）指定。具体环境变量请以官方文档为准。

五、快速入门

5.1 最简示例

先启动 Letta 服务端（自托管），或使用 Letta Cloud 获取 LETTA_API_KEY。

python 复制代码 
import os
from letta_client import Letta

# Cloud 版
client = Letta(token=os.environ["LETTA_API_KEY"])
# 自托管（本地 docker run letta/letta）用：
# client = Letta(base_url="http://localhost:8283")

# 创建 Agent（用 memory_blocks 定义 persona / human）
agent = client.agents.create(
    model="openai/gpt-4.1",
    embedding="openai/text-embedding-3-small",
    memory_blocks=[
        {"label": "persona", "value": "你是一个友好的助手，用简洁的语言回答问题。", "limit": 2000},
        {"label": "human", "value": "用户是一个对AI技术感兴趣的开发者。", "limit": 2000},
    ],
    tools=["web_search"],
)
print(f"Agent ID: {agent.id}")

# 发送消息
resp = client.agents.messages.create(
    agent_id=agent.id,
    messages=[{"role": "user", "content": "你好，请介绍一下你自己。"}],
)

# 遍历消息
for m in resp.messages:
    if m.message_type == "reasoning_message":
        print(f"[思考] {m.reasoning}")
    elif m.message_type == "tool_call_message":
        print(f"[工具调用] {m.tool_call}")
    elif m.message_type == "assistant_message":
        print(f"[助手] {m.content}")

5.2 带记忆的对话

Letta 的核心优势是记忆。下面的示例展示了 Agent 如何自动把用户信息写入 human Block：

python 复制代码 
import os
from letta_client import Letta

client = Letta(token=os.environ["LETTA_API_KEY"])

agent = client.agents.create(
    model="openai/gpt-4.1",
    embedding="openai/text-embedding-3-small",
    memory_blocks=[
        {"label": "persona", "value": "你是一个细心的助手，会记住用户提到的重要信息。", "limit": 2000},
        {"label": "human", "value": "用户信息尚未了解。", "limit": 2000},
    ],
)

# 第一轮：用户介绍自己
client.agents.messages.create(
    agent_id=agent.id,
    messages=[{"role": "user", "content": "我叫李明，是一名前端工程师，主要用React和TypeScript。"}],
)

# 查看 Agent 的 human 记忆块（Agent 会自动更新）
block = client.agents.blocks.retrieve(agent_id=agent.id, block_label="human")
print("=== Human 记忆块 ===")
print(block.value)

# 第二轮：测试记忆
resp = client.agents.messages.create(
    agent_id=agent.id,
    messages=[{"role": "user", "content": "你还记得我是做什么的吗？推荐一些学习资源。"}],
)
for m in resp.messages:
    if m.message_type == "assistant_message":
        print(f"[助手] {m.content}")

你会发现，Agent 自动将用户信息更新到了 human Block 中，并且在第二轮对话中能够准确回忆。

5.3 使用 Archival Memory

Archival Memory 适合存储大量知识：

python 复制代码 
import os
from letta_client import Letta

client = Letta(token=os.environ["LETTA_API_KEY"])

agent = client.agents.create(
    model="openai/gpt-4.1",
    embedding="openai/text-embedding-3-small",
    memory_blocks=[
        {"label": "persona", "value": "你是一个知识库助手，擅长从档案中检索信息回答问题。", "limit": 2000},
        {"label": "human", "value": "用户希望你能记住大量技术文档。", "limit": 2000},
    ],
)

# 写入档案记忆（passages）
client.agents.passages.create(
    agent_id=agent.id,
    text="React 18 引入了并发渲染（Concurrent Rendering），允许 React 同时准备多个版本的 UI。",
)
client.agents.passages.create(
    agent_id=agent.id,
    text="TypeScript 5.0 支持装饰器（Decorators）的新标准，与之前的实验性装饰器不同。",
)

# 让 Agent 基于档案回答（Agent 内部会自动调用 archival 检索）
resp = client.agents.messages.create(
    agent_id=agent.id,
    messages=[{"role": "user", "content": "React 新特性有哪些？"}],
)
for m in resp.messages:
    if m.message_type == "assistant_message":
        print(m.content)

5.4 客户端-服务端架构

Letta 的客户端-服务端分离架构有几个重要优势：

  • 多客户端共享：同一个 Agent 可以被 Python SDK、REST API、Web UI 同时访问
  • 状态集中管理：所有 Agent 状态在服务端统一管理，客户端无状态
  • 水平扩展：服务端可以独立扩展，支持大量并发 Agent
  • 安全隔离：工具执行在服务端沙箱中，客户端无法直接访问服务端资源

六、记忆系统详解

6.1 Core Memory 管理

Core Memory 由一组 Memory Block 承载。创建 Agent 时通过 memory_blocks 初始化；运行中 Agent 会自动改写这些 Block。

手动查看 Block：

python 复制代码 
import os
from letta_client import Letta

client = Letta(token=os.environ["LETTA_API_KEY"])
agent = client.agents.create(
    model="openai/gpt-4.1",
    embedding="openai/text-embedding-3-small",
    memory_blocks=[
        {"label": "persona", "value": "你是一个专业的Python助手。", "limit": 2000},
        {"label": "human", "value": "用户信息尚未了解。", "limit": 2000},
    ],
)

# 查看某个 Block 的当前内容
block = client.agents.blocks.retrieve(agent_id=agent.id, block_label="human")
print(block.value)

# 更新 Block 内容（也可用 append / replace 语义，具体方法名以 SDK 为准）
client.agents.blocks.modify(
    agent_id=agent.id,
    block_id=block.id,
    value="用户李明，前端工程师，技术栈 React + TypeScript，偏好函数式编程。",
)

自动管理： Agent 在对话中会自动调用 core_memory_append 和 core_memory_replace 工具来更新记忆。这个过程由 LLM 自主决策------当它认为某条信息足够重要时，就会写入 Core Memory。

6.2 Archival Memory 操作

Archival Memory 基于向量数据库，支持高效的语义检索：

python 复制代码 
import os
from letta_client import Letta

client = Letta(token=os.environ["LETTA_API_KEY"])
agent = client.agents.create(
    model="openai/gpt-4.1",
    embedding="openai/text-embedding-3-small",
    memory_blocks=[
        {"label": "persona", "value": "你是一个知识库助手。", "limit": 2000},
        {"label": "human", "value": "用户希望你能记住大量技术文档。", "limit": 2000},
    ],
)

# 批量写入
documents = [
    "FastAPI 是一个现代、高性能的 Python Web 框架，基于 Starlette 和 Pydantic。",
    "SQLAlchemy 是 Python 中最流行的 ORM 框架，支持 Core 和 ORM 两种使用模式。",
    "Pydantic v2 使用 Rust 重写了核心验证逻辑，性能较 v1 有显著提升。",
]
for doc in documents:
    client.agents.passages.create(agent_id=agent.id, text=doc)

# 直接检索档案（也可让 Agent 在对话中自动检索）
results = client.agents.passages.list(agent_id=agent.id, query="Python Web 框架性能")
for r in results:
    print(f"[匹配] {r.text}")

说明：passages.list 的检索参数（如 query / limit）随版本可能变化，具体以 SDK 类型定义为准。生产中最常用的方式仍是让 Agent 在对话里自动检索 archival。

6.3 Recall Memory（对话历史）

Recall Memory 存储完整的对话记录，支持按时间和语义检索：

python 复制代码 
import os
from letta_client import Letta

client = Letta(token=os.environ["LETTA_API_KEY"])

# 获取最近若干条消息
messages = client.agents.messages.list(agent_id=agent.id, limit=50)
for m in messages:
    print(m.message_type, getattr(m, "content", ""))

Recall Memory 的检索策略由 Letta 内部自动管理，通常采用最近消息 + 语义相关消息的混合策略。

6.4 自动记忆管理流程

Letta 的自动记忆管理是其最核心的能力之一。当上下文窗口即将满时，Agent 会触发自我反思流程：

复制代码 
触发条件：上下文使用率 > 阈值（默认 80%）
    ↓
1. 分析对话历史，识别重要信息
    ↓
2. 将重要信息压缩后写入 Core Memory 或 Archival Memory
    ↓
3. 总结旧对话，生成摘要替换原始消息
    ↓
4. 释放上下文空间，继续对话

这个过程完全自动化，开发者无需干预。但可以通过配置调整触发阈值和记忆策略。

6.5 自我反思（Self-Reflection）

自我反思是 Letta Agent 的元认知能力。Agent 会定期审视自己的记忆和行为，进行优化：

python 复制代码 
import os
from letta_client import Letta

client = Letta(token=os.environ["LETTA_API_KEY"])

# 让 Agent 反思并更新记忆
resp = client.agents.messages.create(
    agent_id=agent.id,
    messages=[{"role": "user", "content": "请反思一下你对我的了解，看看有没有需要更新的信息。"}],
)
for m in resp.messages:
    if m.message_type == "assistant_message":
        print(m.content)

自我反思的典型场景：

  • 用户偏好发生变化时更新 human Block
  • 发现 Persona 描述不准确时修正
  • 对话过长时压缩历史
  • 检测到矛盾信息时解决冲突

七、Agent 架构

7.1 Agent 配置

新版 SDK 中，创建 Agent 通过 client.agents.create，用模型 handle 字符串（如 openai/gpt-4.1）直接指定模型，用 memory_blocks 定义记忆，用 tools 引用工具名列表：

python 复制代码 
import os
from letta_client import Letta

client = Letta(token=os.environ["LETTA_API_KEY"])

agent = client.agents.create(
    model="openai/gpt-4.1",                       # 形如 "openai/gpt-4.1" / "anthropic/claude-..."
    embedding="openai/text-embedding-3-small",   # 嵌入模型 handle
    memory_blocks=[
        {"label": "persona", "value": "你是一个专业的技术顾问...", "limit": 2000},
        {"label": "human", "value": "用户是一名全栈开发者...", "limit": 2000},
    ],
    tools=["web_search", "run_code"],
)
print(agent.id)

说明：老教程里的 LLMConfig(model_endpoint=..., model_backend=...) 是 0.5.x 的写法，新版已不再需要------直接用 "provider/model" 形式的模型 handle 即可。如需 provider 专属高级参数（如 reasoning、streaming），请以官方 SDK 文档为准。

7.2 Agent 状态图

Letta Agent 的内部状态机：

复制代码 
                    ┌──────────┐
                    │  Created │
                    └────┬─────┘
                         │ create()
                         ▼
                    ┌──────────┐
              ┌────▶│  Ready   │◀────┐
              │     └────┬─────┘     │
              │          │ step()     │
              │          ▼            │
              │     ┌──────────┐      │
              │     │ Thinking │      │
              │     └────┬─────┘      │
              │          │            │
              │    ┌─────┴─────┐      │
              │    ▼           ▼      │
              │ ┌──────┐  ┌────────┐  │
              │ │Tool  │  │Respond │  │
              │ │Call  │  │        │  │
              │ └──┬───┘  └───┬────┘  │
              │    │          │       │
              │    ▼          │       │
              │ ┌──────┐      │       │
              │ │Execute│      │       │
              │ └──┬───┘      │       │
              │    │          │       │
              │    └──────────┘       │
              │                         │
              │    memory full?        │
              └──────┬────────────────┘
                      │ yes
                      ▼
                 ┌──────────┐
                 │Reflecting│
                 └────┬─────┘
                      │
                      ▼
                 (back to Ready)

7.3 Agent 管理

python 复制代码 
import os
from letta_client import Letta

client = Letta(token=os.environ["LETTA_API_KEY"])

# 列出所有 Agent
agents = client.agents.list()
for a in agents:
    print(f"{a.id} - {a.name}")

# 获取 Agent 详情
agent = client.agents.retrieve(agent_id="agent-id-here")

# 更新 Agent 配置
client.agents.modify(
    agent_id=agent.id,
    memory_blocks=[{"label": "persona", "value": "更新后的人格描述...", "limit": 2000}],
)

# 删除 Agent
client.agents.delete(agent_id=agent.id)

方法名（list / retrieve / modify / delete）遵循 V1 SDK 的 snake_case 命名；分页返回的对象结构随版本可能调整，请以 SDK 类型为准。

八、工具系统（Tools）

8.1 内置工具

Letta 提供丰富的内置工具，V1 SDK 中通过名称直接引用（如 web_search、run_code、code_interpreter 等）：

工具名 功能 类别
send_message 向用户发送消息 通信
core_memory_append 追加 Core Memory 记忆
core_memory_replace 替换 Core Memory 区块 记忆
archival_memory_insert 插入 Archival Memory 记忆
archival_memory_search 搜索 Archival Memory 记忆
conversation_search 搜索对话历史 记忆
web_search 网络搜索 网络
run_code / code_interpreter 执行代码 计算

8.2 自定义工具

自定义工具的注册方式随版本演进较快。在 V1 SDK 中，推荐通过 client.tools 体系注册工具（如 client.tools.upsert(...) 或按官方文档提供的装饰器/函数工具写法）。由于自定义工具的具体 API 变化频繁，请务必以官方工具文档为准：https://docs.letta.com/guides/tools

⚠️ 注意 ：自定义工具 API 变化频繁，下方示例仅作示意，不能直接复制运行，请以官方文档为准：https://docs.letta.com/guides/tools

示意形态（以官方文档最新写法为准）：

python 复制代码 
import os
from letta_client import Letta

client = Letta(token=os.environ["LETTA_API_KEY"])

# 自定义工具的典型注册方式（具体 API 以官方文档为准）
# tool = Tool.from_function(fn=my_function)  # 或 client.tools.upsert(...)
# agent = client.agents.create(..., tools=[tool])

def get_weather(city: str) -> str:
    """获取指定城市的当前天气信息。"""
    # 实际调用天气 API
    return f"{city} 当前天气：晴，25°C"

# 注册后将该工具加入 Agent 的 tools 列表即可由 Agent 调用

8.3 工具与记忆交互

Letta 的工具系统与记忆系统深度集成。内置记忆工具（core_memory_append / core_memory_replace / archival_memory_insert / archival_memory_search）让 Agent 能够直接读写自己的记忆；自定义工具也可以调用 SDK 的 client.agents.blocks / client.agents.passages 接口来操作和检索记忆。

九、数据源与 RAG 集成

9.1 数据源架构

Letta 的数据源（Source）系统允许将外部知识源连接到 Agent，实现检索增强生成（RAG）：

复制代码 
┌─────────────┐     ┌──────────────┐     ┌───────────┐
│ 外部数据源   │────▶│  Source     │────▶│  Agent    │
│ (文件/DB/API)│     │  (索引+嵌入)  │     │ (检索+生成)│
└─────────────┘     └──────────────┘     └───────────┘

9.2 连接数据源

python 复制代码 
import os
from letta_client import Letta

client = Letta(token=os.environ["LETTA_API_KEY"])

# 创建数据源
source = client.sources.create(
    name="tech-docs",
    embedding="openai/text-embedding-3-small",
)

# 上传文件到数据源
client.sources.files.upload(source_id=source.id, file_path="./docs/python-guide.pdf")
client.sources.files.upload(source_id=source.id, file_path="./docs/intro.md")

# 将数据源绑定到 Agent
agent = client.agents.create(
    model="openai/gpt-4.1",
    embedding="openai/text-embedding-3-small",
    memory_blocks=[
        {"label": "persona", "value": "你是一个技术文档助手。", "limit": 2000},
        {"label": "human", "value": "用户正在学习 Python。", "limit": 2000},
    ],
)
client.agents.sources.attach(agent_id=agent.id, source_id=source.id)

说明：sources 相关方法名（create / files.upload / agents.sources.attach）以官方最新 SDK 为准，不同小版本可能略有差异。

9.3 RAG 检索流程

当 Agent 收到用户问题时，RAG 流程如下：

  1. 查询理解：LLM 分析用户问题，提取检索关键词
  2. 数据源检索：在绑定的数据源中进行向量相似度搜索
  3. 上下文组装：将检索到的相关片段组装到提示词中
  4. 生成回答：LLM 基于检索到的上下文生成回答
python 复制代码 
import os
from letta_client import Letta

client = Letta(token=os.environ["LETTA_API_KEY"])

# Agent 会自动使用绑定的数据源进行检索
resp = client.agents.messages.create(
    agent_id=agent.id,
    messages=[{"role": "user", "content": "Python 中如何使用 SQLAlchemy 进行异步查询？"}],
)
for m in resp.messages:
    if m.message_type == "assistant_message":
        print(m.content)

十、多智能体系统

10.1 多 Agent 架构

Letta 支持创建多 Agent 系统，不同 Agent 可以有不同的专长和记忆，通过消息传递协作：

复制代码 
          ┌─────────────┐
          │  Orchestrator │  (协调者 Agent)
          │    Agent      │
          └───┬───┬───┬──┘
              │   │   │
     ┌────────┘   │   └────────┐
     ▼            ▼            ▼
┌─────────┐  ┌─────────┐  ┌─────────┐
│Research │  │ Coding  │  │ Review  │
│ Agent   │  │ Agent   │  │ Agent   │
└─────────┘  └─────────┘  └─────────┘

10.2 创建多 Agent 系统

python 复制代码 
import os
from letta_client import Letta

client = Letta(token=os.environ["LETTA_API_KEY"])

# 创建研究 Agent
researcher = client.agents.create(
    model="openai/gpt-4.1",
    embedding="openai/text-embedding-3-small",
    memory_blocks=[{"label": "persona", "value": "你是一个研究专家，擅长搜集和整理信息。", "limit": 2000}],
)

# 创建编码 Agent
coder = client.agents.create(
    model="openai/gpt-4.1",
    embedding="openai/text-embedding-3-small",
    memory_blocks=[{"label": "persona", "value": "你是一个高级程序员，擅长编写高质量代码。", "limit": 2000}],
)

# 创建审查 Agent
reviewer = client.agents.create(
    model="openai/gpt-4.1",
    embedding="openai/text-embedding-3-small",
    memory_blocks=[{"label": "persona", "value": "你是一个代码审查专家，擅长发现代码中的问题。", "limit": 2000}],
)

10.3 Agent 间通信

通过向目标 Agent 发送消息实现协作：

python 复制代码 
import os
from letta_client import Letta

client = Letta(token=os.environ["LETTA_API_KEY"])

# 向 researcher 发送任务
resp = client.agents.messages.create(
    agent_id=researcher.id,
    messages=[{"role": "user", "content": "请研究一下 FastAPI 的最佳实践，并整理成要点。"}],
)
for m in resp.messages:
    if m.message_type == "assistant_message":
        print(m.content)

说明：新版 Agent 间通信更推荐通过 Orchestrator Agent 来协调，或将消息分别发送给各专精 Agent 再汇总。具体编排模式请参考官方多 Agent 文档。

十一、对话管理与会话

11.1 会话管理

Letta 中每个 Agent 都有独立的会话，所有消息都属于这个会话：

python 复制代码 
import os
from letta_client import Letta

client = Letta(token=os.environ["LETTA_API_KEY"])

# 获取消息历史
messages = client.agents.messages.list(agent_id=agent.id, limit=50)
print(f"消息数: {len(messages)}")

11.2 消息结构

Letta 的消息有多种类型（V1 SDK 中以 message_type 字段区分），常见包括：

  • user_message：用户消息
  • assistant_message：助手回复
  • reasoning_message：内部思考（对应老版的 internal_monologue）
  • tool_call_message：工具调用（对应老版的 function_call）
  • tool_return_message：工具返回（对应老版的 function_return）
  • system_message：系统消息

说明：消息类型枚举的具体字符串值随版本可能微调，建议以 SDK 导出的类型为准，不要手写硬编码的字符串常量（老教程里 class MessageType 那种"照抄代码块"的写法在新版已不适用）。

11.3 消息历史流程

一次完整的消息处理流程：

复制代码 
1. 用户发送消息
   ↓
2. 系统将消息加入 Recall Memory
   ↓
3. 组装上下文（Core Memory + 最近对话 + 检索结果）
   ↓
4. LLM 生成内部思考（reasoning_message）
   ↓
5. LLM 决定调用工具（tool_call_message）
   ↓
6. 执行工具，返回结果（tool_return_message）
   ↓
7. 可能重复 4-6 多次
   ↓
8. LLM 生成最终回复（assistant_message）
   ↓
9. 所有消息持久化到 Recall Memory
   ↓
10. 检查是否需要自我反思

示例代码（遍历消息）：

python 复制代码 
import os
from letta_client import Letta

client = Letta(token=os.environ["LETTA_API_KEY"])

resp = client.agents.messages.create(
    agent_id=agent.id,
    messages=[{"role": "user", "content": "测试消息"}],
)

for m in resp.messages:
    if m.message_type == "reasoning_message":
        print(f"[思考] {m.reasoning}")
    elif m.message_type == "tool_call_message":
        print(f"[工具] {m.tool_call}")
    elif m.message_type == "tool_return_message":
        print(f"[返回] {m.tool_return}")
    elif m.message_type == "assistant_message":
        print(f"[助手] {m.content}")

十二、REST API 服务

12.1 API 架构

Letta Server 提供完整的 REST API，支持非 Python 客户端接入（新版路径通常以 /v1 为前缀）：

复制代码 
客户端 (任何语言)
    │
    │ HTTP/JSON
    ▼
Letta Server (FastAPI)
    ├── /v1/agents      - Agent 管理
    ├── /v1/agents/{id}/messages - 消息发送
    ├── /v1/agents/{id}/memory   - 记忆管理
    ├── /v1/sources     - 数据源管理
    ├── /v1/tools       - 工具管理
    └── /health         - 健康检查

说明：V1 SDK 的底层就是调用这些 REST 端点。直接使用 REST 时，路径前缀与字段结构请以官方 API 参考为准（https://docs.letta.com/api-reference）。

12.2 常用 API 端点

bash 复制代码 
# 健康检查
curl http://localhost:8283/health

# 创建 Agent
curl -X POST http://localhost:8283/v1/agents \
  -H "Content-Type: application/json" \
  -d '{
    "model": "openai/gpt-4.1",
    "embedding": "openai/text-embedding-3-small",
    "memory_blocks": [{"label": "persona", "value": "你是一个API测试助手。", "limit": 2000}]
  }'

# 发送消息
curl -X POST http://localhost:8283/v1/agents/{agent_id}/messages \
  -H "Content-Type: application/json" \
  -d '{
    "messages": [{"role": "user", "content": "你好"}]
  }'

# 获取 Agent 记忆
curl http://localhost:8283/v1/agents/{agent_id}/memory

# 列出所有 Agent
curl http://localhost:8283/v1/agents

# 删除 Agent
curl -X DELETE http://localhost:8283/v1/agents/{agent_id}

12.3 API 使用示例（Node.js）

javascript 复制代码 
const LETTA_API = "http://localhost:8283";

async function createAgent(name, persona) {
  const response = await fetch(`${LETTA_API}/v1/agents`, {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
      model: "openai/gpt-4.1",
      embedding: "openai/text-embedding-3-small",
      memory_blocks: [{ label: "persona", value: persona, limit: 2000 }],
    }),
  });
  return response.json();
}

async function sendMessage(agentId, message) {
  const response = await fetch(`${LETTA_API}/v1/agents/${agentId}/messages`, {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({ messages: [{ role: "user", content: message }] }),
  });
  const data = await response.json();
  const reply = data.messages.find((m) => m.message_type === "assistant_message");
  return reply ? reply.content : "无回复";
}

// 使用示例
async function main() {
  const agent = await createAgent("node-agent", "你是Node.js助手。");
  const reply = await sendMessage(agent.id, "介绍一下Node.js的事件循环");
  console.log(reply);
}

main();

十三、项目实战

13.1 项目：个人知识管理助手

构建一个能记住你的学习笔记、自动整理知识、随时回答问题的个人助手。

python 复制代码 
import os
from letta_client import Letta

client = Letta(token=os.environ["LETTA_API_KEY"])

# 创建知识库数据源
source = client.sources.create(
    name="personal-knowledge",
    embedding="openai/text-embedding-3-small",
)
client.sources.files.upload(source_id=source.id, file_path="./notes/note1.md")
client.sources.files.upload(source_id=source.id, file_path="./notes/note2.md")

# 创建知识管理 Agent
agent = client.agents.create(
    model="openai/gpt-4.1",
    embedding="openai/text-embedding-3-small",
    memory_blocks=[
        {"label": "persona", "value": "你是一个专业的个人知识管理助手，擅长整理和检索学习笔记。", "limit": 2000},
        {"label": "human", "value": "用户是一名终身学习者，正在学习AI大模型相关技术。", "limit": 2000},
    ],
    tools=["web_search"],
)

# 绑定知识库
client.agents.sources.attach(agent_id=agent.id, source_id=source.id)

# 使用
client.agents.messages.create(
    agent_id=agent.id,
    messages=[{"role": "user", "content": "我今天学习了 RAG 系统的基本原理，包括文档分块、向量嵌入和检索排序。帮我记录并整理一下。"}],
)

13.2 项目：客户支持系统

构建一个能记住客户历史、自动检索解决方案、升级复杂问题的客户支持系统。

python 复制代码 
import os
from letta_client import Letta

client = Letta(token=os.environ["LETTA_API_KEY"])

# 创建客户支持 Agent
agent = client.agents.create(
    model="openai/gpt-4.1",
    embedding="openai/text-embedding-3-small",
    memory_blocks=[
        {"label": "persona", "value": "你是一个专业的客户支持代表，友好、专业、耐心。", "limit": 2000},
        {"label": "human", "value": "客户信息将在对话中逐步了解。", "limit": 2000},
    ],
    tools=["web_search"],
)

# 模拟客户对话
client.agents.messages.create(
    agent_id=agent.id,
    messages=[{"role": "user", "content": "你好，我是张三，我的订单 ORD001 还没收到，能帮我查一下吗？"}],
)

13.3 项目：代码助手

构建一个能记住项目上下文、理解代码库、提供代码建议的编程助手。

python 复制代码 
import os
from letta_client import Letta

client = Letta(token=os.environ["LETTA_API_KEY"])

agent = client.agents.create(
    model="openai/gpt-4.1",
    embedding="openai/text-embedding-3-small",
    memory_blocks=[
        {"label": "persona", "value": "你是一个高级编程助手，基于实际代码给出具体、可操作的建议。", "limit": 2000},
        {"label": "human", "value": "用户是一名Python开发者，正在开发一个RAG系统。", "limit": 2000},
    ],
    tools=["run_code"],
)

client.agents.messages.create(
    agent_id=agent.id,
    messages=[{"role": "user", "content": "帮我看看 ./app/main.py 这个文件，有什么可以优化的地方？"}],
)

十四、生产部署

14.1 部署架构

生产环境推荐的部署架构：

复制代码 
                    ┌─────────────┐
                    │  Load Balancer │
                    │  (Nginx/ALB)  │
                    └───────┬───────┘
                            │
              ┌─────────────┼─────────────┐
              ▼             ▼             ▼
        ┌──────────┐ ┌──────────┐ ┌──────────┐
        │ Letta    │ │ Letta    │ │ Letta    │
        │ Server 1 │ │ Server 2 │ │ Server 3 │
        └────┬─────┘ └────┬─────┘ └────┬─────┘
             │              │              │
             └──────────────┼──────────────┘
                            │
              ┌─────────────┼─────────────┐
              ▼             ▼             ▼
        ┌──────────┐ ┌──────────┐ ┌──────────┐
        │PostgreSQL│ │ pgvector │ │  Redis   │
        │(元数据)   │ │(向量存储) │ │(缓存)    │
        └──────────┘ └──────────┘ └──────────┘

14.2 生产环境配置

yaml 复制代码 
# docker-compose.prod.yml
version: "3.8"
services:
  letta:
    image: letta/letta:latest
    deploy:
      replicas: 3
      resources:
        limits:
          cpus: "2"
          memory: 4G
    environment:
      - OPENAI_API_KEY=${OPENAI_API_KEY}
      - LETTA_BASE_URL=http://localhost:8283
      - LETTA_LOG_LEVEL=INFO
    depends_on:
      - postgres
    networks:
      - letta-net

  postgres:
    image: pgvector/pgvector:pg16
    environment:
      - POSTGRES_USER=letta
      - POSTGRES_PASSWORD=${DB_PASSWORD}
      - POSTGRES_DB=letta
    volumes:
      - pgdata:/var/lib/postgresql/data
    networks:
      - letta-net

  nginx:
    image: nginx:alpine
    ports:
      - "80:80"
      - "443:443"
    volumes:
      - ./nginx.conf:/etc/nginx/nginx.conf
      - ./certs:/etc/nginx/certs
    depends_on:
      - letta
    networks:
      - letta-net

networks:
  letta-net:
    driver: bridge

volumes:
  pgdata:

14.3 监控与运维

bash 复制代码 
# 健康检查
curl -f http://localhost:8283/health || echo "Letta Server 不健康"

# 查看 Agent 列表
curl http://localhost:8283/v1/agents

# 日志查看
docker-compose logs -f letta

关键监控指标：

  • API 响应时间：P50/P95/P99 延迟
  • Agent 数量：活跃 Agent 总数
  • 消息吞吐量：每秒处理消息数
  • LLM 调用成功率：模型调用失败率
  • 向量检索延迟：Archival Memory 搜索耗时
  • 内存使用率：服务端内存占用

14.4 备份策略

bash 复制代码 
#!/bin/bash
# backup.sh - Letta 数据备份脚本

BACKUP_DIR="/backups/letta"
DATE=$(date +%Y%m%d_%H%M%S)

# 备份 PostgreSQL
docker exec letta-postgres-1 pg_dump -U letta letta > "$BACKUP_DIR/pg_$DATE.sql"

# 压缩备份
tar -czf "$BACKUP_DIR/letta_$DATE.tar.gz" "$BACKUP_DIR/pg_$DATE.sql"

# 清理30天前的备份
find "$BACKUP_DIR" -name "*.tar.gz" -mtime +30 -delete

echo "备份完成: letta_$DATE.tar.gz"

设置定时备份：

bash 复制代码 
# 每天凌晨2点备份
crontab -e
# 添加：0 2 * * * /path/to/backup.sh >> /var/log/letta-backup.log 2>&1

十五、常见问题与排错

15.1 常见错误

错误信息 原因 解决方案
Context window exceeded 上下文超出模型限制 减少消息历史或触发自我反思
Tool not found 工具未注册或名称错误 确认工具已添加到 Agent 的 tools 列表
Embedding dimension mismatch 嵌入维度不匹配 确保数据源和 Agent 使用相同的嵌入模型
Connection refused 服务端未启动 运行 letta server 启动服务
Authentication failed API Key 错误 检查环境变量中的 API Key
Vector search failed 向量数据库异常 检查向量数据库连接和索引状态

15.2 调试技巧

python 复制代码 
import os
import logging
from letta_client import Letta

logging.basicConfig(level=logging.DEBUG)

client = Letta(token=os.environ["LETTA_API_KEY"])

# 打印所有消息类型和内容
resp = client.agents.messages.create(
    agent_id=agent.id,
    messages=[{"role": "user", "content": "测试消息"}],
)
for m in resp.messages:
    print(f"[{m.message_type}]")
    if hasattr(m, "reasoning") and m.reasoning:
        print(f"  思考: {m.reasoning}")
    if hasattr(m, "tool_call") and m.tool_call:
        print(f"  工具: {m.tool_call}")
    if hasattr(m, "tool_return") and m.tool_return:
        print(f"  返回: {m.tool_return}")
    if hasattr(m, "content") and m.content:
        print(f"  内容: {m.content}")

15.3 性能优化

优化一：选择合适的模型

python 复制代码 
# 简单任务用小模型，复杂任务用大模型
simple_agent = client.agents.create(
    model="openai/gpt-4o-mini",
    embedding="openai/text-embedding-3-small",
    memory_blocks=[{"label": "persona", "value": "简单助手", "limit": 2000}],
)
complex_agent = client.agents.create(
    model="openai/gpt-4.1",
    embedding="openai/text-embedding-3-small",
    memory_blocks=[{"label": "persona", "value": "复杂助手", "limit": 2000}],
)

优化二：控制记忆大小

python 复制代码 
# 限制 Archival Memory 检索结果数量（方法名以 SDK 为准）
results = client.agents.passages.list(agent_id=agent.id, query="关键词", limit=3)

优化三：使用流式响应

python 复制代码 
# V1 SDK 支持流式（具体用法以 SDK 为准）
resp = client.agents.messages.create(
    agent_id=agent.id,
    messages=[{"role": "user", "content": "长文本生成任务"}],
    stream=True,
)

十六、框架对比

16.1 功能对比

特性 Letta LangChain AutoGen CrewAI
有状态 Agent ✅ 原生支持 ❌ 无状态为主 ⚠️ 有限支持 ❌ 无状态
分层记忆 ✅ 三级架构 ⚠️ 需自行实现 ❌ 简单记忆 ❌ 简单记忆
自我反思 ✅ 内置 ⚠️ 需自定义 ⚠️ 有限 ❌
工具系统 ✅ 与记忆集成 ✅ 丰富 ✅ 丰富 ✅ 角色化
多 Agent ✅ 消息传递 ⚠️ 需组合 ✅ 对话式 ✅ 角色协作
RAG 集成 ✅ 数据源系统 ✅ 强大 ⚠️ 基础 ⚠️ 基础
服务端部署 ✅ 内置 ❌ 需自建 ❌ 需自建 ❌ 需自建
REST API ✅ 完整 ❌ ❌ ❌
学习曲线 中等 较陡 中等 简单
生产就绪 ✅ ⚠️ 需大量工程 ⚠️ ⚠️

📌 功能对比基于笔者实践整理，仅供选型参考，不代表框架官方能力。各框架能力随版本快速演进，请以官方最新文档为准。

16.2 选择建议

选择 Letta 的场景：

  • 需要 Agent 具备长期记忆和跨会话一致性
  • 构建个性化助手（个人助理、客户支持）
  • 需要快速部署生产级 Agent 服务
  • 重视记忆管理的自动化和智能化
  • 团队希望用统一的服务端管理所有 Agent

选择 LangChain 的场景：

  • 需要高度灵活的自定义链
  • 集成大量第三方工具和数据源
  • 团队有充足的工程能力做二次开发
  • 实验性项目，需要快速验证想法

选择 AutoGen 的场景：

  • 多 Agent 对话式协作是核心需求
  • 需要人类介入的混合智能系统
  • 研究多 Agent 交互模式

选择 CrewAI 的场景：

  • 角色化分工的多 Agent 系统
  • 快速搭建流程化的 Agent 团队
  • 非技术用户也能上手

十七、最佳实践

17.1 记忆管理最佳实践

实践一：精心设计 Persona

Persona 决定了 Agent 的行为边界，要具体但不过度约束：

复制代码 
✅ 好的 Persona：
"你是一个专业的Python后端开发顾问，擅长FastAPI、SQLAlchemy和系统设计。
回答时先给出核心结论，再展开技术细节。代码示例要完整可运行。"

❌ 差的 Persona：
"你是一个有用的助手。"（太模糊）
"你必须用中文回答，每次回答不超过100字，不能用markdown..."（过度约束）

实践二：动态维护 Human 区块

Human 区块应该随对话自动更新，但要控制信息量：

复制代码 
✅ 好的 Human：
"用户张三，全栈开发者，技术栈 Python+React，正在构建RAG系统。
偏好简洁的代码风格，关注性能优化。"

❌ 差的 Human：
"用户今天说了他喜欢喝咖啡，昨天提到了天气，上周说..."（琐碎信息堆积）

实践三：合理使用 Archival Memory

  • 只存储有长期价值的信息
  • 每条信息尽量独立、完整
  • 定期清理过时或重复的条目
  • 利用标签或分类组织大量档案

17.2 核心检查清单

部署 Letta Agent 前的检查清单：

  • Persona 描述清晰、具体、不过度约束
  • Human 区块初始化合理（可以为空，让 Agent 自动学习）
  • 工具集最小化（只添加必要的工具，避免 Agent 混淆）
  • 模型选择匹配任务复杂度
  • 嵌入模型在 Agent 和数据源间一致
  • 生产环境使用 PostgreSQL 而非 SQLite
  • 设置了数据备份策略
  • 配置了监控和告警
  • 测试了长对话场景的记忆管理
  • 验证了自定义工具的错误处理

17.3 反模式

反模式一：把所有信息都塞进 Core Memory

Core Memory 空间有限，塞满琐碎信息会降低 Agent 的注意力。应该只放最关键的信息，其余放 Archival Memory。

反模式二：工具过多过杂

给 Agent 提供几十个工具会导致工具选择错误率上升。应该遵循"最小必要"原则，按场景分组工具。

反模式三：忽略自我反思

有些开发者关闭了自动记忆管理，试图手动控制一切。这违背了 Letta 的设计哲学，也大幅增加了维护成本。

反模式四：单 Agent 承担所有职责

一个 Agent 既做研究又写代码还做审查，效果通常不如三个专精的 Agent 协作。合理拆分职责是多 Agent 系统的关键。

十八、附录：API 速查表

18.1 Python 客户端 API（V1 SDK）

python 复制代码 
import os
from letta_client import Letta

client = Letta(token=os.environ["LETTA_API_KEY"])  # 或 Letta(base_url="http://localhost:8283")

# Agent 管理
client.agents.create(model=..., embedding=..., memory_blocks=[...], tools=[...])
client.agents.retrieve(agent_id)
client.agents.list()
client.agents.modify(agent_id, memory_blocks=[...])
client.agents.delete(agent_id)

# 消息
client.agents.messages.create(agent_id, messages=[{"role": "user", "content": "..."}])
client.agents.messages.list(agent_id, limit=50)

# 记忆（Core Memory Block）
client.agents.blocks.retrieve(agent_id, block_label="human")
client.agents.blocks.modify(agent_id, block_id=..., value=...)

# 档案（Archival Memory）
client.agents.passages.create(agent_id, text="...")
client.agents.passages.list(agent_id, query="...", limit=3)

# 数据源
client.sources.create(name=..., embedding=...)
client.sources.files.upload(source_id, file_path=...)
client.agents.sources.attach(agent_id, source_id)

方法名（如 list / retrieve / modify / blocks / passages / sources）遵循 V1 SDK 命名；分页返回结构、passages.list 的参数等随版本可能调整，请以 SDK 类型定义为准。

18.2 REST API 端点（V1，路径前缀以官方为准）

方法 路径 说明
GET /health 健康检查
POST /v1/agents 创建 Agent
GET /v1/agents 列出 Agent
GET /v1/agents/{id} 获取 Agent 详情
PATCH /v1/agents/{id} 更新 Agent
DELETE /v1/agents/{id} 删除 Agent
POST /v1/agents/{id}/messages 发送消息
GET /v1/agents/{id}/messages 获取消息历史
GET /v1/agents/{id}/memory 获取记忆
POST /v1/sources 创建数据源
POST /v1/sources/{id}/upload 上传文件
POST /v1/agents/{id}/sources 绑定数据源
GET /v1/tools 列出工具
POST /v1/tools 添加工具

18.3 常用命令

bash 复制代码 
# 安装 SDK
pip install letta-client

# 启动服务端
letta server

# 指定端口
letta server --port 9000

# 查看版本
letta --version

# Docker 启动
docker run -p 8283:8283 \
  -e OPENAI_API_KEY=sk-xxx \
  letta/letta:latest

# Docker Compose 启动
docker-compose up -d

# 查看日志
docker-compose logs -f letta

参考资源

注意 ：本文基于 Letta V1 SDK（letta-client，Python，本文撰写时）编写。Letta 自 MemGPT 演进迅速，0.5.x 时代的 create_client() / send_message() / insert_archival_memory() 等接口已在 0.6.0+ 移除，请统一使用 V1 SDK。具体 API、方法名与参数可能随版本变化，实践前请以官方最新文档为准（https://docs.letta.com）。文中示例以 OpenAI 模型为例，实际可替换为 Anthropic / Groq / Ollama 等支持的 provider。
免责声明：本文为第三方学习整理，不属于 Letta 官方文档。框架迭代速度快，文中所有代码、API 仅供学习参考，生产使用请务必查阅官方文档；因版本变更导致的问题，本文不承担责任。

版权与来源声明 ：文中所有代码仅用于学习演示，不构成生产实施建议；所有 API 以项目官方 GitHub 与官方文档为准；开源项目的商标、项目名称归各项目官方所有。
写在最后：Letta 的核心理念------"记忆即灵魂"------不仅仅是一个技术选择，更是对 AI 交互本质的深刻思考。当我们说一个 AI"理解"我们时，我们真正期待的是它能记住我们的偏好、我们的历史、我们的上下文。Letta 用分层记忆、自我反思和有状态架构，让这种期待成为可能。无论你是在构建个人助手、客户支持系统还是知识管理平台，Letta 都值得你深入探索。

相关推荐
机构师1 小时前
AI编程实战：效率与成本，AI 编程的 ROI 怎么算
人工智能·prompt·ai编程·deepseek
ManageEngineITSM1 小时前
什么是CMDB？配置管理数据库的定义、作用与建设方法一文讲清
大数据·数据库·人工智能·资产管理·变更管理
Delite8021 小时前
开口闪点检测智能化升级：工业油品安全检测的标准化解决方案
大数据·人工智能·安全
CallFay云起未来1 小时前
AI客服能不能减少人工回复？从重复咨询到人机协同的落地分析
java·大数据·人工智能·文心一言
Elastic 中国社区官方博客2 小时前
OpenTelemetry Java 扩展：无需分叉 agent 即可自定义追踪
java·大数据·运维·开发语言·数据库·人工智能·elasticsearch
长江后浪博客2 小时前
RIP 颜色管理之 LittleCMS：开源 ICC 色彩管理引擎
人工智能·陶瓷喷墨·littlecms·icc色彩管理·rip软件
美狐美颜sdk2 小时前
直播APP开发如何实现美颜功能？视频美颜SDK接入流程与技术方案解析
大数据·人工智能·音视频·美颜sdk·美颜api
Am-Chestnuts2 小时前
AI 对话里的表格怎么导出成 Excel 还能筛选排序？用DS随心转把数据整理成可分析表格
大数据·人工智能·excel
数据狐(Datafox)2 小时前
京东商品列表API技术解析与落地应用（含标准 JSON 示例）
java·大数据·前端·人工智能·python·数据分析·json
热门推荐
01国内可直接用、免费额度/永久免费的大模型API清单（含 SiliconFlow、火山、阿里、智谱、百度、Kimi、DeepSeek、DMXAPI 等）02GitHub 镜像站点032026 国产 AI 大模型横评：DeepSeek、通义千问、Kimi、文心一言、星火、豆包谁更能打？04历年考研数学一、数学二、数学三真题试卷及答案PDF05微信历史版本含下载地址（ Windows PC | 安卓 | MAC ）及设置微信不更新06Agnes AI 免费 API 接入指南：文本、生图、生视频，一套接口全免费07AI 编程 IDE 全景解析 2026：Agent 全面接管开发链路082026年7月AI圈大地震：GPT-5.6被政府限制、Claude入驻Slack、Anthropic自研芯片09VSCode+CodeX扩展，无法启动10如何新建文件夹？ 电脑新建文件夹的4种方法