Letta：有状态、长期记忆的 Agent 服务器｜部署与使用全指南

适用版本段：本文基于 Letta 开源 API Server（PyPI 包 letta 最新版 0.34.x、Docker 镜像 letta/letta:latest）撰写，调研日期 2026 年 10 月。GitHub 仓库 letta-ai/letta 约 25.2k star，License 为 Apache-2.0。需要特别说明：Letta 官方已把活跃开发转移到新仓库 letta-ai/letta-code（Node.js 系，npm 安装 @letta-ai/letta-code），原 Python 版 V1 API server 已移入 letta-ai/letta 仓库的 archive 分支，PyPI 包与 Docker 镜像仍然可用、文档仍保留在 docs.letta.com，本文讲解的就是这套仍可完整自部署的经典开源 server（即用户俗称的 MemGPT 后继版）。撰写时以 archive 分支 README 与 docs.letta.com 的 V1 文档为准。

Letta（前身是 2023 年 UC Berkeley 的研究项目 MemGPT）是一个「有状态」的 AI Agent 服务器。它的核心思想是：LLM 的上下文窗口不是聊天记录，而是一块由 Agent 自己用工具调用不断改写的「工作内存（core memory）」，加上一个可以搜索的「长期档案库（archival memory）」和完整对话历史（recall memory）。因此 Agent 可以记住用户几周前说过的事、持续学习、自我改进。Letta 以 REST API 的形式提供服务（默认端口 8283），配套官方网页端可视化编辑器 ADE（Agent Development Environment），支持 OpenAI、Anthropic、Ollama 等多种模型后端。

一、项目介绍与适用场景

Letta 的技术定位是「Agent 运行时 + 记忆管理层」：它不是聊天 UI，也不是 RAG 文档检索系统，而是一个把 Agent 状态（memory blocks、对话历史、工具、数据源）持久化到数据库、并通过 REST API 暴露的服务器。任何前端（Slack 机器人、网页、n8n 工作流、Python/TypeScript 客户端）都可以通过 API 给 Agent 发消息。

适用人群	典型用途
想自托管「长期记忆」Agent 的开发者	个人助理、伴侣式机器人、客服记忆体
需要可视化调试 Agent 的研究者	用 ADE 逐条查看 reasoning、编辑 memory block
产品团队	用 REST API / letta-client SDK 把记忆 Agent 嵌入应用
多 Agent 系统实验者	多个 Agent 共享 memory blocks、sleeptime 后台学习

不适合的场景：

只需要一次性问答、不需要跨会话记忆——用普通 LLM API 更简单。
追求最新功能（skills、subagents、channels、MemFS git 记忆）——这些在 Letta Agent SDK / letta-code（TypeScript）里，Python 版 V1 server 已停止活跃开发。
只用 7B 级小模型做后端——记忆编辑是带判断的 tool calling，小模型经常写错 block，官方和社区都建议用能力较强的模型。

二、核心功能逐条拆解

Core memory（核心内存）：Agent 提示词里固定携带的一小批带标签的 memory block（默认有 human 和 persona 两块）。Agent 自己调用 core_memory_append / core_memory_replace 工具来改写它，实现「把重要事实写进工作记忆」。
Archival memory（档案记忆）：基于向量检索的长期存储，Agent 用 archival_memory_insert 写入、用 archival_memory_search 搜索。Docker 版用 PostgreSQL + pgvector 实现。
Recall memory（回忆记忆）：完整对话历史的搜索能力，Agent 可用 conversation_search / conversation_search_date 工具查询「我上周和用户聊过什么」。
Memory blocks 自定义：创建 Agent 时可以声明任意多个带 label、value、limit（字符上限）的 block，例如 facts、policies。
多 Agent 共享 blocks：多个 Agent 可以挂载同一份 block，一个 Agent 写入、其他 Agent 立刻可见，用于构建共享知识的 Agent 群体。
Tools 与自定义工具：内置 memory 系列工具；用户可以注册 Python 源码定义的自定义工具，Letta 从 docstring 自动生成 schema。生产环境可配 E2B 沙箱执行。
Sleeptime agent：后台 Agent，与主 Agent 共享 memory，在主 Agent 空闲时整理、归档、重写记忆（「sleep-time compute」思想的开源实现）。
ADE 可视化编辑器：官方网页 IDE（app.letta.com），连接你的本地/远程 server 后，可以图形化查看 context window、编辑 memory blocks、管理 tools、模拟对话。

ADE 主界面：中间对话、左侧 context window 与 memory blocks

模型无关：同一套 server 可以按 Agent 分别指定 openai/gpt-4o、anthropic/claude-sonnet-4、ollama/qwen3 等模型，以及对应的 embedding 模型。
REST API + SDK：所有能力都有 REST 端点；官方提供 Python 包 letta-client 和 TypeScript 包 @letta-ai/letta-client。

三、全套官方链接

资源	地址
GitHub 仓库（V1 server，已归档）	https://github.com/letta-ai/letta （`archive` 分支）
新一代 Letta（letta-code，活跃开发）	https://github.com/letta-ai/letta-code
官方文档	https://docs.letta.com
V1 SDK 快速上手	https://docs.letta.com/v1-sdk
Docker 部署文档	https://docs.letta.com/guides/selfhosting/postgres
ADE（网页端）	https://app.letta.com
PyPI 包	https://pypi.org/project/letta/ 与 https://pypi.org/project/letta-client/
Docker Hub 镜像	https://hub.docker.com/r/letta/letta
模型排行榜	https://leaderboard.letta.com
License	Apache-2.0（仓库根目录 LICENSE）
社区	Discord: https://discord.gg/letta ｜ Forum: https://forum.letta.com

四、硬件与环境前置要求

项目	要求
操作系统	Linux / macOS / Windows（Windows 建议用 WSL2 或 Docker Desktop）
Python（pip 安装方式）	Python 3.9+（建议 3.10–3.12），含 pip 与 venv
Docker（镜像方式）	Docker Engine 20.10+，建议同时装 Docker Compose v2
CPU / 内存	2 核 / 2 GB 起步（模型不在本机跑时）；本机跑模型另算
GPU	Letta server 本身不需要 GPU；本地推理（Ollama）才需要
磁盘	镜像约 2–3 GB；数据库按对话量增长，预留 5 GB 以上
网络与账号	访问模型 API（OpenAI/Anthropic 等需 API key）；拉取镜像需能访问 Docker Hub
端口	默认 8283（HTTP），需保证未被占用

五、多平台部署步骤

5.1 Docker 官方镜像（推荐，全平台通用）

官方镜像 letta/letta 内置 PostgreSQL + pgvector，一条命令即可启动：

docker run \
  -v ~/.letta/.persist/pgdata:/var/lib/postgresql/data \
  -p 8283:8283 \
  -e OPENAI_API_KEY="sk-你的key" \
  letta/letta:latest

说明：-v 把容器内 PostgreSQL 数据目录持久化到宿主机 ~/.letta/.persist/pgdata；-p 映射 8283 端口；模型 key 通过环境变量注入。启动后访问 http://localhost:8283 会返回 server 信息，http://localhost:8283/v1/health 可用于健康检查。

生产环境（有不可信用户）务必开启密码保护：

docker run \
  -v ~/.letta/.persist/pgdata:/var/lib/postgresql/data \
  -p 8283:8283 \
  --env-file .env \
  -e SECURE=true \
  -e LETTA_SERVER_PASSWORD=yourpassword \
  letta/letta:latest

开启后所有 API 请求需携带请求头 Authorization: Bearer yourpassword。

5.2 Linux（pip 安装）

python3 -m venv ~/letta-venv
source ~/letta-venv/bin/activate
pip install -U letta
letta server --port 8283

pip 安装版默认使用 SQLite，数据存放在 ~/.letta/ 目录下；如需 PostgreSQL，设置环境变量 LETTA_PG_URI（见第六章）。启动后终端会显示 server 地址与可用的 model endpoint。

5.3 macOS

与 Linux 完全一致（建议用 Homebrew 安装 Python 3.11+ 后再建 venv）：

brew install python@3.12
python3.12 -m venv ~/letta-venv && source ~/letta-venv/bin/activate
pip install -U letta
letta server --port 8283

Apple Silicon 上 Docker Desktop 同样可跑官方镜像。

5.4 Windows

官方未提供 Windows 原生安装脚本，推荐两条路（其一即可）：

Docker Desktop：在 PowerShell 中执行 5.1 的 docker run 命令（路径写成 %USERPROFILE%\.letta\.persist\pgdata）。
WSL2：在 Ubuntu 子系统内按 5.2 执行 pip 安装步骤。

5.5 源码编译（开发用途）

git clone https://github.com/letta-ai/letta.git
cd letta && git checkout archive   # V1 server 代码在 archive 分支
pip install -e .
letta server --port 8283

数据库迁移用 Alembic 管理，源码方式启动时会自动执行 alembic upgrade head（日志里可见）。

六、配置文件全部参数解释

Letta 通过环境变量配置，常用项如下（以官方文档为准）：

环境变量	默认值	说明
`OPENAI_API_KEY`	无	OpenAI 模型 key
`OPENAI_BASE_URL`	`https://api.openai.com/v1`	OpenAI 兼容端点地址（接代理/私有网关时改这里）
`ANTHROPIC_API_KEY`	无	Anthropic 模型 key
`OLLAMA_BASE_URL`	无	Ollama 服务地址，如 `http://host.docker.internal:11434/v1`（Docker 内访问宿主机）
`AZURE_API_KEY` / `AZURE_BASE_URL` / `AZURE_API_VERSION`	无	Azure OpenAI 三件套
`GEMINI_API_KEY`	无	Google Gemini
`GROQ_API_KEY`	无	Groq
`TOGETHER_API_KEY`	无	Together AI
`LETTA_PG_URI`	无	连接外部 PostgreSQL（必须已启用 pgvector：`CREATE EXTENSION IF NOT EXISTS vector;`），不设则用镜像内置 PG / SQLite
`SECURE`	`false`	设为 `true` 开启 API 密码保护
`LETTA_SERVER_PASSWORD`	随机生成	密码保护使用的口令
`E2B_API_KEY` / `E2B_SANDBOX_TEMPLATE_ID`	无	开启自定义工具的 E2B 沙箱执行
`LETTA_MEMFS_SERVICE_URL`	无	设为 `local` 启用本地 MemFS（git 记忆文件系统）实验特性

.env 示例（配合 docker run --env-file .env）：

# 模型 key
OPENAI_API_KEY=sk-xxx
ANTHROPIC_API_KEY=sk-ant-xxx
OLLAMA_BASE_URL=http://host.docker.internal:11434/v1
# 安全
SECURE=true
LETTA_SERVER_PASSWORD=change-me
# 数据库（可选，外置 PG）
# LETTA_PG_URI=postgresql://letta:pass@pg.example.com:5432/letta

pip 本地运行时，配置与缓存位于 ~/.letta/（SQLite 数据库、logs 等）。

七、启动、后台常驻、开机自启、改端口

前台启动（pip）：letta server --port 8283；改端口直接换数字即可。

Linux systemd 常驻（/etc/systemd/system/letta.service）：

[Unit]
Description=Letta Agent Server
After=network.target

[Service]
Type=simple
User=letta
EnvironmentFile=/etc/letta/letta.env
ExecStart=/home/letta/letta-venv/bin/letta server --port 8283
Restart=always

[Install]
WantedBy=multi-user.target

sudo systemctl daemon-reload && sudo systemctl enable --now letta

Docker 自启：docker run 加 --restart unless-stopped --name letta；或用 Compose：

services:
  letta:
    image: letta/letta:latest
    restart: unless-stopped
    ports: ["8283:8283"]
    volumes:
      - ~/.letta/.persist/pgdata:/var/lib/postgresql/data
    env_file: .env

Windows：Docker Desktop 勾选「开机启动」+ 容器 restart 策略即可；WSL2 方式可用计划任务在登录时执行 wsl -e bash -lc "letta server"。官方未提供 NSSM 方案，以上为社区惯用法。

反向代理 / HTTPS：ADE 只信任 https 的远程 server（localhost 的 http 例外，Safari 与新 Chrome 除外）。自托管时可用 Caddy：

letta.example.com {
    reverse_proxy 127.0.0.1:8283
}

或者临时用 ssh -L 8283:localhost:8283 user@server 把远程端口转发到本地，ADE 里按「Local server」连接。

八、功能实操教程

以下均假设 server 跑在 http://localhost:8283。Python 客户端：pip install letta-client；TypeScript：npm install @letta-ai/letta-client。

场景 1：创建 Agent 并发消息（curl）

curl --request POST --url http://localhost:8283/v1/agents/ \
  --header 'Content-Type: application/json' \
  --data '{
    "model": "openai/gpt-4o-mini",
    "embedding": "openai/text-embedding-3-small",
    "memory_blocks": [
      {"label": "human",  "value": "Name: 小林. Role: 后端工程师."},
      {"label": "persona","value": "我是有长期记忆的助手，语气温和。"}
    ]
  }'

注意：Docker 自建 server 时 embedding 必填（云端 API 才自动管理）。返回的 JSON 里有 id（形如 agent-abc123）。发消息：

curl --request POST --url http://localhost:8283/v1/agents/agent-abc123/messages \
  --header 'Content-Type: application/json' \
  --data '{"messages": [{"role": "user", "text": "你好，你还记得我是谁吗？"}]}'

返回里能看到 reasoning_message（思考）、tool_call_message（如 core_memory_append）、assistant_message（最终回复）三类消息。

场景 2：Python SDK 读写 core memory

from letta_client import Letta

client = Letta(base_url="http://localhost:8283")
agent = client.agents.create(
    model="openai/gpt-4o-mini",
    embedding="openai/text-embedding-3-small",
    memory_blocks=[
        {"label": "human", "value": "Name: 小林."},
        {"label": "persona", "value": "我是长期记忆助手."},
    ],
)
resp = client.agents.messages.create(
    agent_id=agent.id,
    input="我最近搬去了上海，请记住。",
)
for m in resp.messages:
    print(m.message_type, getattr(m, "content", ""))

# 直接查看/修改 memory block
block = client.agents.core_memory.retrieve_block(agent.id, block_label="human")
print(block.value)
client.agents.core_memory.modify_block(agent.id, block_label="human", value=block.value + " 现居：上海。")

场景 3：ADE 连接本地 server 并可视化编辑

保证 server 运行后，浏览器打开 https://app.letta.com。
点击「Add remote server」/选择「Local server」，地址填 http://localhost:8283（开了密码则同时填 password）。
进入 Agents 列表，点开 Agent，即进入模拟器视图：左侧可查看/编辑 context window 与各 memory block，右侧聊天，底部查看 tool call 明细。

场景 4：使用 archival / recall 记忆

对话中直接要求即可触发内置工具，例如发送「把我们刚讨论的部署参数存进长期记忆」，Agent 会调用 archival_memory_insert；发送「我上周问过什么关于端口的问题」会触发 conversation_search_date。也可在 ADE 的 Archival Memory 面板里手动增删条目、做向量搜索。

场景 5：接入 Ollama 本地模型

启动 server 时注入 OLLAMA_BASE_URL（Docker 内访问宿主机用 http://host.docker.internal:11434/v1），然后创建 Agent：

agent = client.agents.create(
    model="ollama/qwen3",
    embedding="ollama/mxbai-embed-large",   # 需先 ollama pull
)

场景 6：Sleeptime agent 与共享 memory block

创建一个带 sleeptime 后台副本的 Agent（V1 API 中通过 sleeptime 相关参数/标签开启，以当前 docs.letta.com 的 sleeptime 指南为准）：主 Agent 负责对话，后台副本在空闲时整理共享的 memory blocks。多 Agent 共享 block 的做法：先 client.blocks.create(label="team_facts", value="...") 拿到 block.id，再把该 id 传给多个 Agent 的 block_ids，任一 Agent 写入即全员可见。

场景 7：自定义工具

def get_weather(city: str) -> str:
    """查询城市天气（示例）。"""
    return f"{city}: 晴，26℃"

tool = client.tools.upsert_from_function(func=get_weather)
agent2 = client.agents.create(
    model="openai/gpt-4o-mini",
    embedding="openai/text-embedding-3-small",
    tools=[tool.name],
)

Letta 会根据函数签名和 docstring 生成 JSON schema，Agent 即可在对话中调用。

九、全套报错故障排查

现象	原因	解决
`letta: command not found`	venv 未激活 / pip 装到别的 Python	`pip show letta` 确认；激活正确 venv
pip 安装失败（编译错误）	Python 版本过旧或缺编译链	用 Python 3.10+；或改用 Docker
启动报 `port 8283 already in use`	端口被占用	`lsof -i :8283` 找进程，或 `--port 8383` 换端口
启动报 database migration 失败	旧版 `~/.letta` 数据与新版不兼容	备份后删除 `~/.letta` 重建；或用 `alembic upgrade head` 手动迁移（源码方式）
请求返回 401	开了 `SECURE=true` 但没带 Bearer 密码 / key 错	请求头加 `Authorization: Bearer <LETTA_SERVER_PASSWORD>`
返回 401/403 且来源是模型侧	模型 key 错误或欠费	检查 `OPENAI_API_KEY` 等环境变量；在容器内 `env \\| grep KEY` 确认注入成功
创建 Agent 报 embedding 相关错误	Docker 自建未指定 `embedding`	创建时显式传 `embedding`，如 `openai/text-embedding-3-small`
Docker 启动后数据丢失	没挂数据卷	必须挂 `-v ~/.letta/.persist/pgdata:/var/lib/postgresql/data`
容器内连不上宿主机 Ollama	用了 `localhost`	改用 `http://host.docker.internal:11434/v1`（Linux 需加 `--add-host=host.docker.internal:host-gateway`）
Ollama 模型报 404	模型未拉取	`ollama pull <模型名>`
ADE 连不上远程 server	ADE 只允许 https（localhost http 例外）	上反向代理/ngrok，或 `ssh -L` 端口转发
ADE 在 Safari/新 Chrome 连 localhost 失败	浏览器拦截 http localhost	换 Chrome 旧策略不行就改用 ssh 转发或自签 https
回复变乱、忘记写入记忆	后端模型太弱	换 gpt-4o/claude 级别模型；参看 leaderboard.letta.com
`context window exceeded` / 上下文溢出	对话过长、block 写太满	减小 block `limit`、让 Agent 归档到 archival；或换长上下文模型
自定义工具执行报错 / 权限风险	无沙箱	配置 `E2B_API_KEY` + `E2B_SANDBOX_TEMPLATE_ID` 启用沙箱
外置 PG 报 `extension vector does not exist`	未装 pgvector	在库中执行 `CREATE EXTENSION IF NOT EXISTS vector;`
`Memory repo manager not configured`	`LETTA_MEMFS_SERVICE_URL` 没传进容器	检查 `-e` 是否拼写正确
升级后 API 字段变了	V1 API 仍在演进	固定镜像 tag（如 `letta/letta:0.34.x`）并阅读 release notes

十、升级、回滚与卸载

查看版本：pip show letta；Docker 看镜像 tag：docker images letta/letta。
pip 升级：pip install -U letta（数据在 ~/.letta，升级前建议备份）。
Docker 升级：docker pull letta/letta:latest → docker stop letta && docker rm letta → 用原 docker run 命令重建（卷不动，数据保留）。
回滚：pip 用 pip install letta==0.33.2（指定旧版本号）；Docker 拉取旧 tag 如 letta/letta:0.33.2 重建容器。注意数据库迁移一般单向，回滚前务必备份 ~/.letta/.persist/pgdata。
完整卸载： bash pip uninstall letta letta-client docker stop letta && docker rm letta && docker rmi letta/letta rm -rf ~/.letta # 会删除全部 Agent 数据与数据库，确认后再执行

十一、商用许可与合规风险提示

License：Apache-2.0，允许商用、修改、再分发，需保留版权声明与 LICENSE 副本；修改文件建议标注改动。
商标：「Letta」名称与 Logo 属 Letta 公司，再分发衍生产品时避免暗示官方背书。
API 费用：模型调用费用（OpenAI/Anthropic 等）由使用方承担，自行监控额度；开源 server 本身免费。
数据隐私：记忆与对话全部存在你自己的数据库（SQLite/PG），但消息内容会发往所选模型服务商——涉及敏感数据时选本地模型或确认服务商数据处理协议。
出网风险：server 会外连模型 API；自定义工具默认在 server 进程内执行，生产环境必须开 SECURE=true + 密码 + E2B 沙箱。
项目状态：Python 版 V1 server 已归档（仅维护性更新），新建项目请评估是否迁往 letta-code / Agent SDK；长期依赖 V1 需自行承担维护风险。

附录：命令速查

# 安装与启动
pip install -U letta
letta server --port 8283
# Docker
docker run -v ~/.letta/.persist/pgdata:/var/lib/postgresql/data -p 8283:8283 -e OPENAI_API_KEY=sk-xxx letta/letta:latest
docker logs -f letta
# 健康检查
curl http://localhost:8283/v1/health
# SDK
pip install letta-client
npm install @letta-ai/letta-client
# 备份
tar czf letta-backup.tgz ~/.letta

Letta：有状态、长期记忆的 Agent 服务器｜部署与使用全指南

Letta：有状态、长期记忆的 Agent 服务器｜部署与使用全指南

一、项目介绍与适用场景

二、核心功能逐条拆解

三、全套官方链接

四、硬件与环境前置要求

五、多平台部署步骤

5.1 Docker 官方镜像（推荐，全平台通用）

5.2 Linux（pip 安装）

5.3 macOS

5.4 Windows

5.5 源码编译（开发用途）

六、配置文件全部参数解释

七、启动、后台常驻、开机自启、改端口

八、功能实操教程

场景 1：创建 Agent 并发消息（curl）

场景 2：Python SDK 读写 core memory

场景 3：ADE 连接本地 server 并可视化编辑

场景 4：使用 archival / recall 记忆

场景 5：接入 Ollama 本地模型

场景 6：Sleeptime agent 与共享 memory block

场景 7：自定义工具

九、全套报错故障排查

十、升级、回滚与卸载

十一、商用许可与合规风险提示

附录：命令速查

周若琳

文章目录