LettaXLL 智能体记忆系统

面向 openKylin 操作系统的多源融合智能体记忆提取、分层治理、统一检索与精准遗忘系统。

LettaXLL 基于 Letta（MemGPT）v0.16.8 进行低侵入式扩展，在保留原生 Agent 调度、消息管理与工具执行能力的基础上，补充结构化偏好与知识管理、三级记忆流转、异构检索、自然语言遗忘以及 OS 级安全管控能力，覆盖记忆的「采集—清洗—提取—存储—流转—检索—遗忘」完整生命周期。

本项目由 Mobisys 小队 开发，用于中国研究生操作系统开源创新大赛。

项目特性

• 多源数据治理：统一接入对话消息、工具结果、用户行为和手动配置，完成清洗、质量分级与标准化。
• 结构化偏好记忆：通过规则、NER 与 LLM 协同提取偏好，支持场景隔离、冲突裁决和版本回滚。
• 可复用知识记忆：将知识写入 Passage，并结合 PostgreSQL 关键词检索与 Milvus 语义向量检索。
• 三级记忆流转：构建短期内存、中期 JSON 记录和长期数据库三级存储，支持溯源与重要性淘汰。
• 统一检索与 RAG：跨源检索、RRF 融合、Reranker 精排、查询缓存和向量冷热分层协同优化。
• 敏感检测与精准遗忘：应用层四级检测、自然语言遗忘、跨存储级联清理、缓存同步与审计留痕。
• OS 级支撑：集成 fanotify、cgroup v2、namespace 和 systemd-journald，提供内核拦截、资源管控、用户隔离与系统审计。

技术方案

1. 三级记忆架构

记忆层级	存储介质	主要内容	生命周期
短期记忆	内存 / Messages	当前会话、工具结果和滑动窗口上下文	会话结束或 FIFO 淘汰
中期记忆	JSON 追加式记录	原始消息、质量评分、加工状态和溯源链接	异步加工，按重要性评分淘汰
长期记忆	PostgreSQL + Milvus Lite	Block 偏好、Passage 知识和向量索引	持久化存储与按需检索

中期层将消息接收与偏好、知识提取解耦。消息到达后先追加写入并立即返回，后台异步完成结构化提取，使长期记忆能够反向定位到原始对话。

2. 偏好—知识异构读写分流

• 偏好记忆属于确定性状态，写入结构化 Block，读取时采用精准字段或关键词匹配，不建立向量索引。
• 知识记忆属于开放性内容，写入结构化 Passage，同时建立 Milvus 向量索引；检索时融合 PostgreSQL 关键词结果与 GTE 语义向量结果。
• 两类结果经统一检索入口完成融合排序，并作为 RAG 上下文注入 Agent。

3. LVP 治理骨架

• Ledger：追加记录原始事件、中期记忆和溯源关系，避免覆盖历史处理轨迹。
• Policy：统一执行敏感检测、偏好冲突裁决、知识去重与时效管理、缓存失效和遗忘策略。
• Views：根据用户、场景和查询请求，从短期消息、Block、Passage 与允许访问的中期记录中生成即时上下文。

4. 端侧检索与资源优化

系统采用 Dense + Sparse + RRF + Reranker 的混合检索链路，并通过以下机制控制端侧成本：

• 查询缓存：命中后跳过嵌入、粗排与精排全链路。
• 冷热分层：冷向量移出 Milvus，但原文保留在 PostgreSQL，重新命中后再嵌入回插。
• 摘要压缩：中期层提炼主题、意图与关键实体，减少 RAG 注入的 token 和噪声。
• cgroup v2：使用 MemoryHigh 和 MemoryMax 提供软硬两级内存保护。

5. 安全与遗忘

应用层通过「对抗预处理 → 增强正则 → NER → 语义消歧」识别敏感信息，内核层使用 fanotify 对绕过应用管道的文件写入进行补盲。自然语言遗忘支持删除范围预览和确认，随后清理 PostgreSQL、Milvus、JSON 记录并同步刷新系统消息缓存；受消息协议约束的对话记录采用软标记并从后续检索中排除。审计日志仅保留操作元数据与内容哈希。

部署指南

环境要求

组件	要求
操作系统	openKylin 2.0+
Python	3.12，不支持 3.13+
PostgreSQL	14+，推荐 16+
内存	最低 8 GB，推荐 16 GB+
磁盘	最低 20 GB，推荐 50 GB+
GPU	无强制要求，可使用 CPU 推理

核心依赖包括 Milvus Lite、GTE-base、可选的 BGE-reranker-v2-m3、Transformers、PyTorch 和 psutil。

一键安装

git clone <你的 GitLink 仓库地址> lettaxll
cd lettaxll

# 默认数据库用户、密码和库名均为 letta
bash install.sh

安装脚本会完成系统依赖安装、PostgreSQL 初始化、Python 虚拟环境创建、依赖安装、GTE-base 下载、数据库迁移以及 .env 生成。

配置

在项目根目录 .env 中配置：

OPENAI_API_KEY=sk-your-api-key
OPENAI_BASE_URL=https://dashscope.aliyuncs.com/compatible-mode/v1
LETTA_PG_URI=postgresql+pg8000://letta:letta@localhost:5432/letta

LETTA_EMBEDDING_BACKEND=local
LETTA_EMBEDDING_MODEL=gte
LETTA_VECTOR_BACKEND=kylin

生产环境请替换默认数据库密码，不要将 API Key 提交到仓库。

启动

# 终端 1：启动后端
source envs/letta/bin/activate
export $(grep -v '^#' .env | xargs)
letta server --port 8283

# 终端 2：启动前端
python3 chat_server.py

访问地址：

• 后端服务：http://localhost:8283
• 前端页面：http://localhost:3000/demo.html

健康检查：

curl http://localhost:8283/v1/health

更完整的手动安装、API 使用和故障排查说明见：

LettaXLL智能体记忆系统_部署与使用手册.md

项目测试

测试环境为 openKylin 2.0、x86_64 四核 CPU、16 GB 内存、Python 3.12.2、PostgreSQL 16 与 Milvus Lite。

核心指标	测试结果	数据集 / 测量方式
偏好提取准确率	81.36%	preference_dataset，200 条
知识检索 Recall@5	83.1%	MS MARCO，30 个查询 / 500 条语料
知识冲突处理正确率	90.0%	dedup_testset，120 条目
检索延迟 P95	467.4 ms	200 次全链路请求，满足 ≤500 ms
敏感信息识别 F1	72.68%	AI4Privacy，2280 条
资源占用	367.2 MB	cgroup v2 memory.peak 实测
OS 级机制	4 项	fanotify、cgroup v2、namespace、journald

项目结构

lettaxll/
├── letta/
│   └── memory_integration/   # 自研记忆管理核心模块
├── tests/
│   └── benchmarks/           # 评测与基准脚本
├── docs/                     # 项目文档与 README 图片
├── chat_server.py            # 前端静态服务与 API 代理
├── install.sh                # 一键安装脚本
├── .env                      # 本地配置，不应提交密钥
└── README.md

未来拓展

当前版本已完成分层存储、异构分流和 LVP 治理等核心能力，后续计划包括：

• 双时间戳机制：引入交易时间与有效时间，处理地理位置、订单状态等具有明确生效边界的动态状态。
• 程序性记忆 Skill：从多次成功的工具调用轨迹中提炼可复用技能组件，减少重复长链推理。
• 轻量级知识图谱：从 Passage 中抽取实体关系，将单条匹配扩展为多跳关联检索。
• 联邦遗忘：支持遗忘指令在多设备、多实例间同步执行。
• 更深层 OS 集成：将安全拦截扩展到 IPC 和网络数据出口，并通过 D-Bus 向 UKUI 与系统服务开放记忆能力。

以上内容均为规划方向，尚未纳入当前版本的已实现能力。

安全边界

• 精准遗忘仅覆盖系统管理的 PostgreSQL、Milvus、JSON 记录和缓存，不处理用户自行创建的离线备份、人工副本或系统快照。
• fanotify 内核拦截、cgroup v2 管控等能力需要 root 权限或 systemd 服务配置。
• 对话消息为保护工具调用与返回消息的配对结构，采用软标记并从检索结果中排除。
• 生产环境必须修改默认数据库凭据，并通过环境变量或密钥管理服务提供 API Key。

致谢

本项目基于 Letta（原 MemGPT）开源框架进行二次开发，并使用或参考了 openKylin、Milvus Lite、PostgreSQL、达摩院 GTE-base、BAAI BGE-reranker-v2-m3、Microsoft Presidio、spaCy、PyTorch 与 Transformers 等开源项目和技术成果。

感谢 Letta 与 openKylin 社区提供的基础能力，感谢阿里云 DashScope 提供的大模型接口支持，感谢中国研究生操作系统开源创新大赛组委会提供的交流与实践平台。