一种上下文工程的范式-Letta（MemGPT）项目拆解

项目原地址：github.com/letta-ai/le...

Letta 项目全面总结与详细解说

📋 项目概述

Letta （原名 MemGPT）是一个用于构建有状态AI智能体 的开源平台。它的核心创新在于为AI智能体提供了高级内存管理系统，使得智能体能够学习、记忆并在时间推移中自我改进。

核心定位

平台性质：AI智能体开发平台
核心价值：让AI智能体具备长期记忆和自我改进能力
技术基础：基于MemGPT研究论文中提出的"LLM操作系统"（LLM Operating System）概念

🧠 核心概念详解

1. 内存层次结构 (Memory Hierarchy)

Letta的核心创新在于实现了分层内存系统，模拟了人类记忆的层次结构。与传统LLM只能访问有限上下文窗口不同，Letta智能体拥有多层次的内存系统，能够自主管理和检索信息。

scss 复制代码

内存系统
├── 上下文内存 (In-Context Memory)
│   └── 内存块 (Memory Blocks) - 可编辑的持久化内存片段
└── 上下文外内存 (Out-of-Context Memory)
    ├── 归档内存 (Archival Memory) - 长期存储
    └── 召回内存 (Recall Memory) - 语义搜索

1.1 上下文内存 (In-Context Memory)

定义与特点：

直接可见性：上下文内存中的所有内容都会直接提供给LLM，作为system prompt的一部分
始终可用：无论上下文窗口如何变化，内存块始终在智能体的"视野"中
有限大小：受限于上下文窗口大小，需要精心管理
即时访问：无需搜索即可使用，类似于人类的"工作记忆"

核心组件 - 内存块 (Memory Blocks)：内存块是上下文内存中的可编辑、持久化的信息片段。在与LLM交互时，这部分内容一定会挂载到system prompt上。

内存块的特点：

✅ 可编辑 ：智能体可以通过工具调用（如 core_memory_replace、core_memory_append）自主修改内存块内容
✅ 持久化：存储在数据库中，跨会话保持，不会因为对话结束而丢失
✅ 可共享：多个智能体可以共享同一个内存块，实现组织级信息共享
✅ 类型化 ：常见类型包括：
- persona：定义智能体的角色、性格和行为方式
- human：存储用户的关键信息和偏好
- tasks：记录智能体需要完成的任务列表

内存块的工作机制：

初始化：创建智能体时可以指定初始内存块
挂载：每次LLM调用时，所有内存块都会被格式化并添加到system prompt
更新：内存块支持两种更新方式：
- 方式一：同一智能体自主管理 ：智能体在对话过程中，通过调用工具（core_memory_replace、core_memory_append）自主更新内存块。这种方式让智能体能够实时响应用户交互，立即更新记忆。
- 方式二：专门的Sleep-time Agent管理 ：当启用 enable_sleeptime 时，系统会创建一个专门的"睡眠时间智能体"（Sleep-time Agent）。这个后台智能体与主智能体共享相同的内存块，在主智能体完成用户交互后，会在后台分析对话历史并更新内存块。这种方式可以：
  - 减轻主智能体的负担，让它专注于用户交互
  - 在后台进行更深入的内存分析和整理
  - 定期运行（可配置频率），确保内存的及时更新
- 注意：Sleep-time Agent 主要使用 memory_replace、memory_insert、memory_rethink 等专门的内存管理工具来更新内存块，而不是使用 archival_memory_insert（归档内存插入工具）。
同步：内存块的修改会立即持久化到数据库，并在下次调用时生效。当多个智能体共享内存块时，更新会自动同步到所有相关智能体

内存块 vs 归档内存的管理分工：

内存块（Core Memory） ：由主智能体或 Sleep-time Agent 管理，使用 core_memory_replace、core_memory_append 或 memory_replace、memory_insert 等工具
归档内存（Archival Memory） ：主要由主智能体使用 archival_memory_insert 工具管理，Sleep-time Agent 通常不直接使用此工具

示例：

python 复制代码

# 创建带有内存块的智能体
agent = client.agents.create(
    memory_blocks=[
        {
            "label": "persona",
            "value": "我是一个友好的AI助手，擅长技术咨询"
        },
        {
            "label": "human",
            "value": "用户喜欢编程和AI技术，偏好Python语言"
        }
    ]
)

# 智能体在对话中可以自主更新内存块
# 例如：当用户纠正信息时，智能体会调用 core_memory_replace 更新内存块

1.2 上下文外内存 (Out-of-Context Memory)

当上下文窗口不足以容纳所有信息时，智能体需要访问上下文外内存。这部分内存不在system prompt中，但智能体可以通过工具调用主动检索。

归档内存 (Archival Memory)

定义：归档内存是智能体的长期存储空间，用于保存重要的反思、洞察和结构化信息。

特点：

无限大小：不受上下文窗口限制，可以存储大量信息
语义搜索：使用向量嵌入技术，支持基于语义相似度的搜索
主动管理 ：智能体可以主动插入（archival_memory_insert）和搜索（archival_memory_search）信息
结构化存储：支持标签（tags）分类和时间过滤

使用场景：

存储重要的项目决策和讨论要点
保存用户偏好和长期目标
记录智能体的反思和洞察
存储不适合放在内存块但需要长期记忆的信息

工作机制：

插入：主智能体通过 archival_memory_insert 工具将信息存储到归档内存
- 内容会被转换为向量嵌入
- 可以添加标签便于分类
- 自动记录时间戳
- 注意：archival_memory_insert 主要由主智能体使用。Sleep-time Agent 通常不使用此工具，它们专注于管理内存块（core memory blocks）。Voice Sleep-time Agent 可以通过专门的 store_memories 工具间接向归档内存插入内容。
搜索：智能体通过 archival_memory_search 工具检索信息
- 使用语义相似度匹配（而非关键词匹配）
- 支持标签过滤和时间范围过滤
- 返回按相关性排序的结果
- 主智能体和 Sleep-time Agent 都可以使用此工具搜索归档内存

示例：

python 复制代码

# 智能体可以主动存储重要信息
archival_memory_insert(
    content="用户计划在Q2启动新项目，重点关注AI模型优化",
    tags=["projects", "planning"]
)

# 智能体可以搜索相关信息
archival_memory_search(
    query="Q2项目计划",
    tags=["projects"],
    top_k=5
)

召回内存 (Recall Memory)

定义：召回内存是智能体的对话历史数据库，包含所有过往的交互消息。

特点：

完整历史：存储智能体与用户的所有对话记录
语义检索：支持基于语义的对话搜索，而非简单的关键词匹配
时间感知：可以按时间范围过滤搜索结果
角色过滤：可以只搜索特定角色（user/assistant/tool）的消息

使用场景：

回忆之前讨论过的话题
查找特定时间段的对话内容
检索与当前问题相关的历史对话
理解对话的上下文和演进过程

工作机制：

自动记录：所有消息自动存储到召回内存
搜索：智能体通过 conversation_search 工具检索历史对话
- 使用语义搜索找到相关内容
- 支持时间范围过滤（start_date、end_date）
- 支持角色过滤（只搜索特定角色的消息）
- 返回匹配的消息及其上下文

示例：

python 复制代码

# 智能体可以搜索历史对话
conversation_search(
    query="数据库迁移讨论",
    start_date="2024-01-15",
    end_date="2024-01-20",
    roles=["assistant", "user"]
)

1.3 内存系统的协同工作

三种内存类型协同工作，形成完整的内存体系：

上下文内存（内存块）：提供即时可用的核心信息，始终在"视野"中
归档内存：存储重要的长期信息，需要时通过语义搜索召回
召回内存：保存完整的对话历史，用于回忆和上下文理解

智能体自主管理流程：

智能体接收用户消息
检查上下文内存（内存块）是否包含足够信息
如果不够，智能体决定搜索归档内存或召回内存
检索到的信息被添加到当前上下文
智能体根据新信息更新内存块（如果需要）
生成响应

这种设计使得智能体能够：

突破上下文窗口限制：通过分层内存系统管理无限的历史信息
自主决策：智能体自主决定何时搜索、何时更新内存
持续学习：在交互过程中不断更新和完善记忆

2. 智能体上下文工程 (Agentic Context Engineering)

智能体通过以下机制自主管理上下文窗口：

编辑内存块 ：使用 core_memory_replace 和 core_memory_append 更新内存块内容
删除内存块：移除不需要的信息，释放上下文空间
搜索归档内存 ：使用 archival_memory_search 检索长期存储的信息
搜索对话历史 ：使用 conversation_search 回忆过往对话
总结消息：当消息历史过长时自动总结，压缩上下文占用

3. 持续自我改进的智能体 (Perpetual Self-Improving Agents)

每个智能体都是一个单一实体，具有：

无限的消息历史：所有对话都被持久化，不受上下文窗口限制
跨会话记忆：智能体记住之前的所有交互，形成连续的记忆流
自我更新能力：智能体可以更新自己的记忆和行为，在交互中不断改进
长期一致性：通过内存系统保持跨时间的一致性，就像真实的人格

🔧 核心功能模块

1. 智能体系统

Letta支持多种类型的智能体，满足不同场景需求：

标准智能体：基础智能体实现，支持完整的内存管理和工具调用
版本化智能体：不同架构版本的智能体，逐步改进和优化
临时智能体：无持久化状态的智能体，适合一次性任务
语音智能体：支持语音交互的智能体，处理语音输入和输出

2. 工具系统

Letta支持多种工具类型，扩展智能体的能力：

内置工具：网络搜索、代码执行、文件操作、语义搜索等
MCP工具：支持Model Context Protocol服务器集成，动态加载工具
自定义工具：支持用户定义的工具函数，自动生成工具模式

3. 多智能体架构

Letta支持多智能体协作模式，实现分工协作和资源共享：

Sleep-time Agents（睡眠时间智能体）

概念：Sleep-time Agents是后台运行的"潜意识"智能体，专门负责内存管理和编辑任务。

工作机制：

当创建智能体时启用 enable_sleeptime，系统会自动创建一个专门的Sleep-time Agent
Sleep-time Agent与主智能体共享相同的内存块，可以访问和修改主智能体的内存
主智能体完成用户交互后，Sleep-time Agent会在后台运行，分析对话历史并更新内存块
可以配置运行频率（如每5次对话运行一次），平衡内存更新及时性和系统资源消耗

优势：

职责分离：主智能体专注于用户交互，后台智能体处理内存管理
深度分析：Sleep-time Agent可以在后台进行更深入的内存分析和整理
性能优化：避免主智能体在处理用户请求时同时进行内存管理，提高响应速度
自动同步：内存块的更新会自动同步到主智能体，无需手动操作

共享内存

多智能体共享：多个智能体可以共享同一个内存块，实现协作和信息共享
组织级共享：支持组织级别的共享内存，多个智能体可以访问共同的知识库
实时同步：当共享内存块被更新时，所有相关智能体都能立即看到最新内容

4. 文件系统集成

Letta提供了完整的文件系统集成能力，使智能体能够访问、搜索和管理文件。

4.1 文件存储架构

Letta使用三层数据库结构来存储和管理文件：

files 表（FileMetadata）：存储文件的元数据信息
- 文件名、路径、类型、大小等基本信息
- 文件处理状态（PENDING、COMPLETED、ERROR）
- 关联的组织和数据源信息
file_contents 表（FileContent）：存储文件的完整文本内容
- 一对一关系：每个文件对应一条内容记录
- 支持大文件存储（最大50MB）
- 内容持久化存储在数据库中，而非文件系统
files_agents 表（FileAgent）：文件与智能体的关联表
- 多对多关系：一个文件可以附加到多个智能体
- 记录文件的打开状态和可见内容片段
- 跟踪最后访问时间（用于LRU缓存策略）

4.2 文件附加方式

文件可以通过两种方式附加到智能体：

方式一：通过文件夹（Folder）附加

python 复制代码

# 1. 创建文件夹
folder = client.folders.create(name="my_project")

# 2. 上传文件到文件夹
client.folders.files.upload(
    folder_id=folder.id,
    file=open("config.py", "rb")
)

# 3. 将文件夹附加到智能体
client.agents.folders.attach(
    agent_id=agent.id,
    folder_id=folder.id
)

方式二：通过数据源（Source）附加

python 复制代码

# 创建数据源并附加文件
source = client.sources.create(name="codebase")
# ... 上传文件到数据源 ...
client.agents.sources.attach(
    agent_id=agent.id,
    source_id=source.id
)

4.3 文件工具功能

智能体可以使用多种文件工具来访问和管理文件：

grep_files - 文件内容搜索

功能：使用正则表达式在文件内容中搜索匹配模式
特点：
- 支持完整的Python正则表达式语法
- 默认大小写不敏感
- 支持文件名过滤（include 参数）
- 支持上下文行显示（context_lines 参数）
- 分页显示结果（每页20个匹配）
使用场景 ：
- 查找TODO注释：grep_files(pattern="TODO", include="*.py")
- 搜索函数定义：grep_files(pattern="^def\s+\w+", include="*.py")
- 查找错误处理：grep_files(pattern="except|raise|Error", include="*.py")

open_files - 打开文件查看

打开文件并显示指定范围的内容
支持指定起始行号和行数
打开的文件会被包含在智能体的上下文窗口中

semantic_search_files - 语义搜索

使用向量嵌入技术进行语义搜索
基于含义而非关键词匹配
适合查找概念相关的文件内容

grep_files - 文件搜索

在文件名中搜索匹配模式

4.4 文件访问机制

文件内容加载：

文件内容存储在数据库的 file_contents 表中
当需要访问文件时，从数据库加载完整内容
使用 LineChunker 将内容格式化为带行号的格式

LRU缓存策略：

跟踪文件的最后访问时间（last_accessed_at）
当打开文件数超过限制时，自动关闭最久未访问的文件
缓存的是文件的可见内容片段（visible_content），而非完整内容
优化内存使用，只保留打开文件的格式化内容

性能优化：

文件大小限制：单文件最大50MB，总计200MB
超时控制：搜索操作30秒超时
分页显示：每页最多显示20个匹配结果
正则表达式验证：防止复杂正则表达式导致性能问题

4.5 支持的文件格式

文本格式 ：.txt, .md, .json, .py, .js, .ts 等
文档格式 ：.pdf（自动提取文本）
其他格式：支持所有可提取文本内容的文件类型

4.6 文件系统集成的工作流程

文件上传：用户上传文件到文件夹或数据源
内容提取：系统自动提取文件文本内容并存储到数据库
文件附加：将文件夹或数据源附加到智能体
文件访问：智能体通过工具调用搜索、打开和查看文件
上下文集成：打开的文件内容会被包含在智能体的上下文窗口中
自动管理：系统自动管理文件打开状态和缓存策略