KylinMem

项目简介

KylinMem 是面向 openKylin 的多 Agent 记忆服务。项目将对话、工具结果、手动输入和文档转化为可检索、可更新、可遗忘的记忆，让 Agent 在持续交互中使用用户偏好、工作知识与历史事件。

项目以 Memory Manager 承载记忆处理，通过 Unix Socket 向 Agent 和 Web 页面提供统一服务。平台同时接入麒麟本地嵌入与向量数据库，并结合 systemd、cgroup v2、eBPF LSM 和系统审计，管理记忆服务的运行资源与文件访问。UKUI 桌面联动把文档记忆接入文件管理器、设置入口和桌面通知。

本文命令均在项目根目录执行。首次安装需要网络和 sudo 权限，日常对话与 Web 页面由普通桌面用户启动。

应用场景

持续对话与个性化辅助。 Agent 记录用户明确表达的偏好，并在后续回答中检索相关内容。用户可以直接表达偏好变化或遗忘意图，由记忆层处理对应记录。

多 Agent 协作。 不同 Agent 通过同一常驻服务访问记忆，服务端统一管理存储连接与请求。用户、Agent 命名空间和会话可见性规则共同控制数据访问。

桌面文档辅助。 用户在 Peony 中将文本文件加入记忆，随后通过聊天检索文档内容。文档管理支持查看、归档和删除，并通过桌面通知反馈操作结果。

系统保护与可视化演示。 Web 页面集中展示记忆处理、服务状态、资源指标和审计日志。专项测试通过真实文件访问与资源负载，验证访问策略、审计送达和资源限制。

主要功能

模块	功能
记忆摄取	输入规范化、清洗、敏感内容处理、结构化事件提取
记忆管理	偏好、知识与情景分类管理，行为证据聚合，版本与生命周期管理
记忆检索与遗忘	按身份和会话查询，构建回答上下文，识别自然语言遗忘意图
文档记忆	文档分块、来源关联、检索增强回答、归档与删除
Provider 配置	云端与麒麟本地链路切换，健康诊断，数据目录与向量空间分离
平台与运行时	统一入口、Agent 注册、Unix Socket RPC、常驻服务管理
资源管理	systemd 服务托管，cgroup v2 的 CPU、内存和任务数计量与限制
文件保护	eBPF LSM 检查文件打开、删除和重命名，按服务 cgroup 授权
操作审计	应用事件归档、JSONL 哈希链、Journald 投影、auditd 系统规则
桌面与 Web	Peony 右键操作、桌面通知、设置入口、对话与测试可视化

架构与代码目录

CLI Agent / Web Panel / UKUI 桌面入口
                  |
          平台客户端与 Unix Socket
                  |
        常驻 Memory Service
                  |
           Memory Manager
                  |
       提取、分类、检索与生命周期
                  |
       LLM / Embedding / 向量存储 / SQLite

systemd + cgroup：服务托管与资源管理
eBPF Guard：独立守护进程与内核文件访问控制
Audit + Journald + auditd：应用与系统操作记录

目录或文件	职责
`run.sh`、`agent_entry.py`	命令入口与功能分发
`launcher/`	配置加载、Provider、服务编排、安装与资源管理
`memory_manager/`	记忆业务、处理流水线与存储管理
`agents/`	对话 Agent、数据集评测与系统测试
`webpanel/`	Python Web 后端与可视化页面
`audit/`、`ebpf_guard/`	审计与文件保护
`provider_adapters/`	麒麟向量数据库适配器
`desktop_integration/`	UKUI 桌面入口、通知和 Peony 插件
`mem0/`	项目复用的 mem0 基础组件
`tests/`、`memory_manager/tests/`	平台与记忆层自动化测试

系统环境

完整功能面向 openKylin Nile 系列桌面系统，使用 UKUI、systemd 用户服务和 D-Bus 会话。系统集成已在 Linux 6.6、x86_64 环境验证。eBPF 运行要求内核提供 BTF、启用 BPF LSM，且活动 LSM 列表包含 bpf；资源管理要求 cgroup v2。

安装时应登录 UKUI，并在普通用户终端操作。项目目录、用户运行目录和用户配置目录需要可写。模型下载、源码构建及 Python 依赖安装需要可用网络；API Key 应由部署者配置。

依赖要求

安装脚本负责检查并安装以下依赖。源码构建用于补齐软件源未提供或不可用的开发工具。

类别	主要依赖
Python	Python 3.12、venv、开发头文件、仓库内 mem0 及其依赖
Web	FastAPI、Uvicorn、tomlkit
构建工具	Git、GCC/G++、Make、pkg-config、Clang/LLVM
eBPF	bpftool、libbpf、libelf、zlib、当前内核 BTF
审计	auditd、libsystemd 开发包、systemd-python
麒麟 AI	kytensor-server、CN-CLIP 模型、Vector Engine 及匹配的 SDK
桌面	Peony、libpeony-dev、Qt5、qmake、PyQt5、通知服务

Python 基础依赖定义在 requirements-minimal.txt，Web 依赖定义在 requirements-web.txt。Vector Engine 运行库与开发头文件应保持版本匹配，构建脚本会检测 SDK 连接接口。

构建与安装

首次安装

取得完整项目源码后，在项目根目录执行：

./pre-install.sh --dry-run
./pre-install.sh

安装流程依次检查桌面会话和系统能力，安装软件包，补齐源码构建工具，配置本地 AI 服务，创建 Python 虚拟环境，再构建并部署平台组件。终端会提示输入当前配置所需的 API Key，并输出阶段结果和故障处理指引。

bpftool 的源码构建使用 Linux v6.6 固定提交，下载顺序为国内镜像优先。Vector Engine 开发包缺失时，脚本按已安装运行库版本选择对应 SDK 源码，补齐头文件。eBPF 构建从当前内核 BTF 生成 vmlinux.h，随后编译 BPF 对象。

安装完成后检查服务并执行正式链路验证：

./run.sh status --json
./run.sh guard status --json
./run.sh demo

配置文件

config.toml 管理 Provider、服务、资源限制、审计、Guard 和桌面功能；.env 保存个人密钥等环境变量。手动准备环境文件时，从 .env.example 建立 .env，保留已有个人配置，不将密钥提交到版本库。

两套 Provider 配置如下，实际启用项由 [provider].profile 决定：

Profile	向量嵌入	向量数据库
`cloud-default`	智谱`embedding-3`，2048 维	本地 Qdrant
`local-kylin`	kytensor/Triton CN-CLIP，1024 维	openKylin Vector Engine

LLM 的服务商和模型在各 profile 中配置。按所选链路填写 DEEPSEEK_API_KEY、ZHIPUAI_API_KEY 等必要密钥。查看解析结果并检查可用性：

./run.sh config --json
./run.sh doctor

修改运行配置后执行 ./run.sh service apply。调整 Guard 保护配置后执行 sudo ./run.sh guard apply。不同 profile 使用独立的数据目录与 collection，切换后应重新检查服务状态。

开发构建与更新安装

依赖齐全后，可分别构建三个本地组件：

bash ebpf_guard/build_bpf.sh
bash scripts/build_kylin_vector_adapter.sh
./run.sh desktop build-plugin

更新源码后，使用平台安装命令重建组件并更新服务部署：

sudo ./run.sh install

重复安装保留个人配置和记忆数据，并重启相关服务。请在停止对话和测试后执行。预安装阶段记录位于 build/pre-install.log。

运行方法

Web 可视化界面

./run.sh web

入口检查正式服务并打开默认浏览器，页面地址为 http://127.0.0.1:8765。页面提供对话、会话切换、记忆与文档管理、处理时间线、系统状态、审计日志和测试入口。Enter 发送消息，Shift+Enter 换行。

需要指定端口或关闭自动打开浏览器时执行：

./run.sh web --port 8766 --no-browser

Web 不使用 sudo 启动。按 Ctrl+C 退出 Web 后端，常驻记忆服务继续运行。网页会话列表仅在本次 Web 运行期间保存，记忆数据由正式服务持久保存。

命令行对话

./run.sh run --agent memory-chat

可依次输入“我喜欢吃肯德基”“我喜欢吃麦当劳”，再询问“我喜欢吃什么”。自然语言输入也支持偏好变化和遗忘意图。记忆层根据输入处理记录，使用 /mem 检查实际存储结果。

指令	作用
`/mem`	查看当前身份可见的普通记忆
`/doc`	查看文档记忆
`/forget <主题>`	请求遗忘指定主题
`/quit`	退出对话

CLI 与 Web 共用记忆服务。两端先检索上下文，再生成回答，最后提交用户原话给记忆层。助手回复不作为用户偏好的提取证据。

UKUI 桌面联动

安装 Peony 插件后，在文件管理器中右键选择本地 UTF-8 编码的 .txt 或 .md 文件，执行加入记忆或遗忘操作。操作结果通过桌面通知反馈；加入的文档可在对应身份的聊天与文档列表中查看。

./run.sh desktop doctor --json
./run.sh desktop settings
./run.sh desktop demo

服务与日志

./run.sh service status
./run.sh service restart
./run.sh service logs --follow
./run.sh guard status --json
sudo ./run.sh guard logs
journalctl SYSLOG_IDENTIFIER=kylin-memory -f -o cat

应用 Audit 记录保存在配置的 JSONL 归档中，并投影到 Journald。正式 Guard 独立归档文件访问事件；auditd 记录配置和安装文件的系统操作。关闭服务时分别执行 ./run.sh service stop 与 sudo ./run.sh guard stop；停止 Guard 会解除其文件保护。

测试方法

完整的测试脚本、数据集、实验配置、原始结果与基线材料见 tests/ 目录，其中的 README.md 说明了各材料的用途与使用方式。

自动化回归

.venv/bin/python -m pytest -q tests memory_manager/tests

默认测试配置排除标记为 integration 和 real_api 的用例。需要外部模型或服务的测试应单独准备环境，并按对应测试说明执行。

记忆能力与多 Agent 测试

./run.sh run --agent excel-eval
./run.sh run --agent test-example
./run.sh run --agent multi-agent-memory-test

excel-eval 读取 agents/test-0/dataset_full.xlsx，按编号逐条写入并触发式评测记忆能力，报告保存在 agents/test-0/results/，包含逐题判定、未满分项、指标汇总、阶段延迟与运行信息。指标分两批：题号 1–286 对应原指标测试（数据集编号 1–1400），题号 330–429 对应决赛新增的精准遗忘测试（数据集编号 1601–1700），分别保存为两份报告。

test-example 读取 agents/test-0/dataset.json，使用临时 SQLite 与本地 Qdrant 检查写入、检索和用户隔离，输出成功率、Hit@K、Recall@K、MRR 与延迟。报告保存在 agents/test-0/results/，临时存储在测试结束后清理。

multi-agent-memory-test 通过正式 Memory Service 模拟多个 Agent 请求，使用测试身份检查交叉访问，并在结束时清理本次测试记忆。记忆能力测试可能调用配置的模型 API，应准备有效密钥和网络。

正式服务与系统集成测试

./run.sh demo
sudo ./run.sh system-test
sudo ./run.sh system-test --rounds 30

demo 检查正式服务链路，覆盖服务状态、Provider、Audit、cgroup、Guard、服务授权访问、RPC 审计和外部访问阻断。它使用专用演示文件，不写入业务记忆。

system-test 在临时目录中构造受保护文件，并创建独立的资源限制测试单元。测试覆盖合法访问、不同路径访问、追加、截断、删除、重命名、动态注册和并发读取，同时统计审计送达及 cgroup 限流。报告保存在 agents/os-test/results/，结束时清理临时资源。

已完成的一次 30 轮测试包含 1620 次访问操作，30/30 轮通过。其中，1440 次非授权访问均被阻断，180 次合法访问均被放行；阻断审计与 Journald 记录均为 1440/1440，cgroup 限流验证为 30/30。该结果对应指定数据集和测试环境，新增场景应以实际报告为准。

已知限制与使用边界

系统能力依赖宿主环境。 完整平台需要可用的 systemd、桌面 D-Bus、cgroup v2 和 BPF LSM。缺少内核支持时，需要补齐内核配置并重启；安装脚本会显示对应阶段和处理指引。其他发行版及架构的完整功能未完成同等验证。

文件保护以已注册对象和授权身份为边界。 Guard 周期扫描保护目录，新文件从生成到注册存在刷新间隔。当前检查点覆盖文件打开、删除和重命名，测试结果不代表所有文件操作和攻击方式的覆盖率。

资源指标按服务边界统计。 Memory Service 的 cgroup 指标反映该服务及其进程的资源消耗。独立运行的 kytensor、Vector Engine 等服务需要分别观察。内存阈值配置为 auto 时不写入显式上限，应以实际 cgroup 状态确认限制。

记忆处理受模型与检索结果影响。 提取和关系判定使用模型输出，回答上下文来自相关记忆检索。一次未召回不等同于记录不存在，写入、更新和遗忘结果应结合记忆列表与处理日志确认。

桌面与 Web 有明确的输入范围。 桌面文件入口接受本地 UTF-8 .txt、.md 文件，默认大小上限为 32 KiB，可通过配置调整。Web 面向本机演示，启动入口监听回环地址；远程多人访问与公网部署未在本项目中验证。

开源组件

项目基于 mem0 OSS 的部分基础能力开发，使用 Qdrant、openKylin AI SDK、Linux BPF、systemd、auditd、Qt 和 Peony 等组件。记忆处理、运行时编排、系统保护、桌面接入和测试代码按上述目录组织；第三方组件的许可证与声明随对应代码保留。