LettaXLL 智能体记忆系统

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

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

一、项目简介

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

项目针对现有智能体记忆方案的三个原生缺陷展开：

其一，通用方案把全部对话与实体信息一律存入向量库、仅靠语义相似度检索，而业务系统大量场景（账号、编号、状态类信息）要求的是强一致性精准匹配，向量检索会召回语义近似但无关的内容，因此本项目把记忆按性质分流，确定性状态与开放性内容走上不同的读写与治理通道。

其二，向量库不区分信息的时效性，同一实体的多版本状态会同时进入上下文，造成决策混乱，因此本项目引入双时间戳时态管理，把「随时间软降权」扩展为「生命周期明确的状态到期即失效」。

其三，通用方案的记忆能力全部停留在应用进程内，对操作系统的使用仅限于文件读写与数据库连接，因此本项目把记忆系统下沉为受内核直接管控的对象，使用 fanotify、cgroup v2、namespace 与 systemd-journald 提供拦截、资源保护、用户隔离与系统级审计。

二、应用场景

企业数字员工与客服系统。 客服与数字员工需要长期记住用户的偏好、历史诉求与业务状态（如订单状态、订阅状态）。这类场景对记忆的要求是双重的：偏好与状态必须精确，不能被语义近似的旧值污染；同时又要能按用户要求彻底清除某些信息以满足合规要求。本项目的偏好—知识分流通道与双时间戳机制直接对应前一项，溯源链路驱动的精准遗忘对应后一项。

多用户共享的桌面与工作站环境。 openKylin 面向的是多用户操作系统场景，同一台主机上不同用户的智能体助手不应共享记忆存储。本项目通过 systemd 模板服务实例为每个用户分配独立的 PostgreSQL 数据库与独立 cgroup 配额，实现物理隔离而非仅逻辑隔离。

资源受限的端侧设备。 在无独立显卡、内存有限的国产化终端上部署智能体助手时，记忆检索的延迟与内存占用直接决定可用性。本项目采用本地推理的中文嵌入模型、查询缓存、向量冷热分层与 cgroup v2 软硬双限，不依赖外部向量服务，也不强制要求 GPU。

涉及敏感信息与合规审计的场景。 医疗、金融、政务类应用要求同时满足「敏感信息不得落盘」与「每一次记忆操作可审计」。本项目用应用层四级检测加内核态 fanotify 补盲满足前者，用 systemd-journald 中的操作元数据与内容哈希满足后者，两者不需要在可审计性与隐私之间取舍。

需要沉淀操作经验的自动化场景。 运维类数字员工反复执行同类任务时，重复的长链条推理成本很高。本项目把反复成功的工具调用轨迹按确定性规则提炼为可复用技能并挂载到智能体，使同类任务不必重新推导，且技能的产生过程不消耗模型推理。

三、主要功能

1. 三级记忆架构

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

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

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

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

两者的冲突治理也彼此不同：偏好是「同一谓词不同取值」，适合规则化裁决；知识是「同一主题不同内容」，适合语义相似度判断。

3. LVP 治理骨架

系统按 Ledger–Policy–Views 三层组织，把「数据怎么存」与「模型能看到什么」分离：

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

4. 端侧检索与资源优化

系统采用「稠密语义向量 + 稀疏关键词双路召回 → 倒数排名融合（RRF）→ 精排重排序」的混合检索链路，并通过以下机制控制端侧成本：

• 查询缓存：命中后跳过嵌入、粗排与精排全链路。
• 冷热分层：冷向量移出向量库，但原文保留在 PostgreSQL，重新命中后再嵌入回插。
• 摘要压缩：中期层提炼主题、意图与关键实体，减少 RAG 注入的 token 和噪声。
• cgroup v2：提供内存软限与硬限两级保护，内存压力上升时由内核回收，而非进程被直接杀死。

5. 敏感检测与精准遗忘

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

6. 双时间戳时态一致性

偏好与知识等「无明确失效点」的变化走时间衰减软降权，旧值随评分下降逐步让位；而地理位置、订单状态等「有明确生效边界」的状态需要硬断言，系统为此引入交易时间与有效时间双时间戳：

• 自动判定：写入前由生命周期分类器识别——带显式生命周期短语（「有效期 3 天」「到月底」「下周换」）或状态类谓词（当前位置、订单状态、订阅状态等）的偏好被打上有效期，用户习惯类偏好继续走软降权。
• 块内携带：每条状态记录携带交易时间与有效截止（缺省长期有效），并可预约未来生效的状态。
• 写时过滤：冲突裁决时已过期的存量偏好被直接替换，不受软衰减阈值限制；写块时过滤过期条目，长期记忆块只承载当前有效状态，因此不会召回过期值。过期值保留在版本快照与溯源账本中，支持追溯与回滚。

旧格式偏好行按长期有效处理，解析、裁决与展示行为与既往版本一致。

7. 程序性记忆 Skill 自进化

偏好回答「喜欢什么」，知识回答「知道什么」，程序性记忆回答「该怎么做」。系统把智能体反复成功执行过的流程沉淀为可复用技能，全程确定性规则，不调用大模型：

• 采集：每轮对话后把工具调用链整理成一条轨迹，追加写入账本；记忆系统自身的治理动作也有统一步骤名，一并与工具链记账，因此不依赖演示数据。
• 挖掘：按工具链相似度聚类，以支持度（≥3 次）与成功率（≥60%）双门槛筛选，再用最长公共子序列提取稳定主流程、差异提取条件分支、失败步骤归纳回退建议。
• 固化：生成精简的技能说明（实测约 435 字符），以技能块挂载到该 Agent，重复挖掘时原地更新。
• 复用：技能进入原生「可用技能」渲染，Agent 可「看见」做法；系统还会按当前任务主动检索并注入匹配的技能。

技能按 Agent 隔离，可回溯到来源轨迹，同样纳入遗忘治理；技能库按「新鲜度 + 支持度」淘汰并归档，归档后可恢复，并记录命中次数与最近命中时间。

8. 操作系统级支撑

系统集成四项操作系统机制，把记忆系统从被保护的应用变为受内核直接管控的对象：

• fanotify：在 VFS 层监听受保护目录的写入请求，在内核态完成敏感模式匹配并拒绝，使数据在到达磁盘之前即被阻断，为应用层检测管道补盲。
• cgroup v2：通过 systemd 服务模板设定内存软限（MemoryHigh）与硬限（MemoryMax）、CPU 配额与进程数上限，在内存压力上升时触发内核回收，使系统在负载下表现为性能下降而非服务崩溃。
• namespace：为同一主机上的不同用户分配独立命名的数据库与独立 cgroup 配额，实现物理隔离。
• systemd-journald：记忆写入、读取、遗忘与偏好版本切换四类操作统一写入系统日志，应用进程崩溃不影响日志完整性。

9. 技术栈总览

四、系统环境

组件	要求
操作系统	openKylin 2.0+（x86_64），内核 6.x
Python	3.12（安装脚本自动安装）
PostgreSQL	14+，推荐 16+，需 pgvector 扩展
包管理器	apt 或 dnf
内存	最低 8 GB，推荐 16 GB+
磁盘	最低 20 GB，推荐 50 GB+
GPU	无强制要求，可使用 CPU 推理
权限	基础功能普通用户即可；fanotify 拦截与 cgroup 管控需 root 或 systemd 服务配置

五、依赖要求

系统软件包（由 install.sh 自动安装，apt 与 dnf 两套分支）：

python3.12、python3.12-venv、python3.12-dev、postgresql、postgresql-client、build-essential（dnf 下为 gcc/gcc-c++/make）、libpq-dev、git、curl、wget、libsqlite3-dev。

Python 依赖：全部声明在 src/pyproject.toml，由安装脚本创建虚拟环境后统一安装。核心包括 SQLAlchemy 2（异步）、Alembic（数据库迁移）、Pydantic 2、FastAPI 与 uvicorn、pg8000、Transformers 与 PyTorch（本地嵌入推理）、kylin-ai-vector-engine（openKylin 系统内置向量引擎）、spaCy 与 Microsoft Presidio（NER 敏感识别）、psutil、requests、NLTK。

模型文件：

• iic/nlp_gte_sentence-embedding_chinese-base（GTE-base，768 维中文语义嵌入，安装脚本自动下载）
• BAAI/bge-reranker-v2-m3（精排模型，可选，未安装时自动跳过精排环节）
• spaCy zh_core_web_md 与 en_core_web_sm（NER 双模型）

外部服务：

• 大模型接口，需 OpenAI 兼容端点。测试环境使用阿里云 DashScope 的 qwen-plus，也可换用任意兼容端点或本地 vLLM（仓库提供 src/deploy/docker-compose-vllm.yaml）。
• PostgreSQL 16 与 pgvector 扩展。kylin-ai-vector-engine 为 openKylin 系统内置的向量引擎，经本地 Unix socket 提供服务，无需额外部署。

六、构建方法

6.1 项目结构

LettaXLL/
├── README.md                     本文件
├── src/                          项目源代码
│   ├── letta/                    后端主体
│   │   └── memory_integration/   自研记忆管理核心模块
│   ├── tests/                    上游单元测试与集成测试
│   ├── alembic/                  数据库迁移（含 alembic.ini 与迁移脚本）
│   ├── scripts/                  运维脚本与工具
│   ├── deploy/                   部署配置（Dockerfile、compose、nginx、init.sql）
│   ├── demo.html                 前端页面
│   ├── chat_server.py            前端静态服务与 API 代理
│   ├── install.sh                一键安装脚本
│   └── pyproject.toml            依赖声明
├── docs/                         项目文档与配图
├── tests/                        测试及验证材料（测试报告、评测脚本、数据集）
├── demo/                         可运行的前端验证界面
└── presentation/                 决赛演示 PPT 与视频

6.2 一键安装

install.sh 以脚本自身所在目录为安装根目录，因此可从任意位置执行：

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

# 默认数据库用户、密码和库名均为 letta，可用环境变量覆盖：
#   PG_USER=myuser PG_PASSWORD=mypass PG_DB=mydb bash src/install.sh
bash src/install.sh

安装脚本按顺序完成七步：安装系统依赖 → 配置 PostgreSQL 并建库 → 创建 Python 虚拟环境 src/envs/letta 并安装依赖 → 配置向量数据库目录 → 下载 GTE-base 模型 → 执行数据库迁移（alembic -c alembic/alembic.ini upgrade head）→ 生成配置文件 src/.env。

6.3 配置

安装完成后在 src/.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-engine

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

6.4 容器化部署（可选）

src/deploy/ 下保留了上游 Letta 的 Dockerfile 与多个 compose 配置，供容器化部署时参考。本项目的功能验证与性能测试均在 openKylin 原生环境（由 install.sh 完成的本地部署）下完成，容器方式未纳入评测范围；如需使用，请按本机环境调整镜像与挂载路径。

七、运行方法

需要两个终端。

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

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

访问地址：

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

健康检查：

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

demo/ 目录下另有一份独立的前端验证界面（demo/demo.html 与 demo/chat_server.py），用于在不启动完整环境时演示核心功能，启动方式同上，详见 demo/README.md。

八、测试方法

8.1 单元测试与集成测试

cd src
source envs/letta/bin/activate
python -m pytest tests/ -q

8.2 记忆系统专项测试

自研记忆模块的专项测试位于 src/tests/，包括 test_memory_integration.py、test_preference_extraction.py、test_knowledge_extraction.py、test_knowledge_dedup_milvus.py、test_memory_flow_retrieval.py、test_sensitive_forgetting.py、test_semantic_forget_vector.py、test_kernel_interception.py、test_temporal_metrics_local.py 等。

8.3 评测与基准脚本

各章节的评测脚本统一放在项目根的 tests/测试脚本/，均为无外部依赖的独立脚本，可单独运行：

# 例：双时间戳时态一致性
python tests/测试脚本/bench_dual_timestamp.py

# 例：资源占用基线
python tests/测试脚本/resource_baseline.py

对应关系（详见 tests/LettaXLL智能体记忆系统_测试报告.md）：偏好提取与冲突消融 ablate_conflict.py；知识检索 evaluate.py --public-datasets --module knowledge；跨语言检索 evaluate_crosslingual.py；知识消融 knowledge_ablation.py；记忆流转消融 test_memory_flow_ablation.py；重要性淘汰 evaluate_importance_eviction.py；统一检索消融 test_unified_retrieval_ablation.py；重排延迟 evaluate_rerank_latency.py；冷热分层 evaluate_cold_tiering.py；资源基线 resource_baseline.py；cgroup 硬限与压力 test_cgroup_limit.py、test_cgroup_pressure.py；双时间戳 bench_dual_timestamp.py；技能自进化 bench_skill_evolution.py；技能库 bench_skill_library.py；技能注入 bench_skill_injection.py；技能淘汰 bench_skill_eviction.py；治理流量接入 bench_governance_wiring.py。

8.4 实测结果

测试环境为 openKylin 2.0、x86_64 四核 CPU、16 GB 内存、Python 3.12.2、PostgreSQL 16 与 kylin-ai-vector-engine，大模型为 qwen-plus。

核心指标	测试结果	赛题阈值	数据集 / 测量方式
偏好提取准确率	81.36%	—	preference_dataset，200 条，以人工标注为真值
知识检索召回率（K=5）	83.1%	—	MS MARCO，30 个查询 / 500 条语料
知识冲突处理正确率	90.0%	—	dedup_testset，120 条目
检索响应延迟（P95）	195.5 ms	≤500 ms	200 次端到端全链路请求，含 embedding + 向量检索 + rerank
敏感信息识别 F1	72.68%	—	AI4Privacy，2280 条
模块资源占用	367.2 MB	—	cgroup v2 memory.peak 实测，与未启用记忆模块的基线对比
操作系统机制（4 项）	4/4 验证通过	≥2 项	fanotify 内核拦截敏感写入并阻断；cgroup v2 两档阈值 MemoryHigh=500 MB（软限）/ MemoryMax=800 MB（硬限），实测峰值 367.2 MB 均未触发，下调至 300 MB / 400 MB 压测确认两档生效；namespace 按用户独立隔离；journald 四类记忆操作留痕

九、已知限制

本项目当前版本的能力边界如下，均已在设计文档与测试报告中记录。

操作系统机制的部署前提。 fanotify 内核拦截与 cgroup v2 资源管控通过 systemd 服务模板部署后完整生效，需要 root 权限或相应的 systemd 配置；未启用这两项机制时，记忆系统的其余功能不受影响。

精准遗忘的覆盖范围。 遗忘覆盖系统自身管理的全部存储，即结构化数据库、向量索引、中期记忆账本与系统消息缓存。用户自行创建的离线备份、人工副本或系统快照不在处理范围内，这属于遗忘机制普遍面对的边界。

对话记录的处理方式。 对话消息需要与工具调用的请求与返回保持配对关系才能保证上下文结构完整，因此删除这类记录时采用软标记并从后续检索结果中排除，既完成擦除又不破坏对话结构；审计日志仅保留操作元数据与内容哈希，不保留明文。

部署形态。 面向单机与端侧场景设计，一台主机独立完成记忆的存储、检索与治理，不依赖外部向量服务或分布式组件。

首次运行开销。 GTE-base 与可选的精排模型需在首次使用前下载，此后嵌入与精排推理完全在本地完成，不再产生网络调用开销。

凭据与密钥。 安装脚本生成的默认数据库凭据（用户、密码、库名均为 letta）仅适用于本地验证；生产环境必须替换，API Key 应通过环境变量或密钥管理服务提供，不要提交到仓库。

致谢

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

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