KylinMem

1. 项目简介

KylinMem 是面向 openKylin/Linux 的多 Agent 记忆中枢。项目以 Memory Manager 作为唯一记忆业务后端，通过本地 C/S 架构向多个 Agent 提供记忆写入、检索、管理和遗忘能力，并在平台层集成 Provider 切换、常驻服务、资源管控、审计、eBPF 文件保护和 UKUI 桌面功能。

项目解决以下核心问题：

• 多个 Agent 通过统一服务共享本地记忆后端，避免多进程直接竞争 SQLite 和本地向量库。
• 偏好、知识、情景和文档进入统一写入、检索与生命周期链路。
• user_id、agent_id 和 session_id 共同构成记忆隔离边界。
• 云端与 openKylin 本地 Provider 通过 profile 切换，并使用独立数据目录和 collection。
• systemd/cgroup、Audit、Journald、auditd 和 eBPF LSM 约束并保护常驻记忆服务。
• Peony、UKUI 通知和设置入口把记忆能力接入桌面文件操作场景。

1.1 核心能力

领域	核心实现	验证方式
记忆管理	清洗、敏感检测、结构化提取、分类管理、生命周期、精准遗忘、统一检索	数据集 Agent、集成测试、交互式对话
多 Agent 共享	单一 Memory Service、Unix Socket RPC、服务端并发与写操作串行化	多 Agent 隔离测试
Provider	cloud-default 与 local-kylin profile、健康诊断、向量空间隔离	./run.sh doctor
资源管控	systemd user service、cgroup v2 CPU/内存/任务计量与限制	./run.sh status --json、系统测试
文件保护	eBPF LSM、服务 cgroup 授权、动态 inode 注册、阻断审计	./run.sh demo、./run.sh system-test
操作审计	AuditEvent、隐私过滤、JSONL 哈希链、Journald、auditd 规则	journalctl、状态接口、系统测试
UKUI 联动	Peony 右键菜单、文档记入与遗忘、桌面通知、设置入口	./run.sh desktop demo

1.2 默认与本地 Provider

config.toml 提供两套运行组合：

Profile	LLM	Embedding	Vector Store	数据目录
cloud-default	DeepSeek deepseek-v4-flash	智谱 embedding-3，2048 维	本地 Qdrant	data/
local-kylin	DeepSeek deepseek-v4-flash	kytensor/Triton CN-CLIP，1024 维	openKylin Vector Engine	data/local-kylin/

默认使用 cloud-default。两个 profile 使用不同的数据目录、collection 和向量维度，切换时不会混用向量数据。

2. 运行说明

2.1 openKylin 一键安装

在已登录的 UKUI 用户终端中执行：

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

pre-install.sh 负责：

1. 检查 openKylin、UKUI 用户会话、systemd user manager 和 D-Bus。
2. 安装 Python 3.12、编译工具、auditd、eBPF、Peony 和 openKylin AI 依赖。
3. 检查 BTF、BPF LSM、bpffs 和 cgroup v2。
4. 构建 bpftool、Vector Engine adapter、eBPF object 和 Peony 插件。
5. 配置 kytensor 模型目录与 Vector Engine 用户服务。
6. 创建 .venv 并安装项目依赖。
7. 调用 sudo ./run.sh install 安装 Memory Service、Guard、auditd 规则和桌面集成。

安装完成后检查平台状态：

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

./run.sh demo 验证 Memory Service、Provider、AuditRuntime、cgroup、eBPF Guard、服务 cgroup 授权、RPC 审计和外部文件访问阻断。

2.2 Python 基础环境

仅运行 Python 记忆功能时，可以手动创建虚拟环境：

Linux：

sudo apt install python3.12-venv
python3.12 -m venv .venv
.venv/bin/python -m pip install -r requirements-minimal.txt

Windows：

python -m venv .venv
.venv\Scripts\python.exe -m pip install -r requirements-minimal.txt

requirements-minimal.txt 以 editable mode 安装仓库内的 mem0/ 包。

2.3 配置密钥与 Profile

复制环境变量模板：

cp .env.example .env

默认链路需要：

DEEPSEEK_API_KEY=your-deepseek-key
ZHIPUAI_API_KEY=your-zhipu-key

Provider、模型、维度、collection、数据目录和本地服务地址由 config.toml 统一管理：

[provider]
profile = "cloud-default"

使用其他环境文件时设置：

AGENT_ENV_FILE=/path/to/agent.env ./run.sh config

检查入口解析结果和 Provider 健康状态：

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

2.4 启动基本对话 Agent

安装常驻服务并启动默认 memory-chat：

./run.sh service install
./run.sh

也可以显式指定 Agent：

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

交互命令：

命令	作用
/mem	查看当前用户和 Agent 命名空间中的记忆
/doc	查看当前用户的文档记忆
/forget <主题>	执行主题级精准遗忘
/quit、/exit	退出 Agent

对话调用链为：

memory-chat
  -> SocketMemoryService
  -> Unix Socket
  -> MemoryServiceRuntime
  -> ManagerMemoryService
  -> MemoryAPI

每轮对话先检索记忆上下文，再调用 LLM 生成回答，最后将完整对话轮次送入 Memory Manager 写入链路。

不使用常驻服务时，可创建隔离的进程内测试后端：

./run.sh run --standalone

该模式使用独立临时 SQLite 和 Qdrant 目录，退出时清理测试资源。

2.5 常驻服务管理

./run.sh service install
./run.sh service apply
./run.sh service start
./run.sh service stop
./run.sh service restart
./run.sh service status
./run.sh service logs --follow
./run.sh service uninstall

查看服务、Provider、cgroup、Audit 和 Guard 聚合状态：

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

修改 config.toml 后执行 ./run.sh service apply，使 systemd unit 和运行中服务使用新的配置。

2.6 使用 openKylin 本地 Profile

将 config.toml 改为：

[provider]
profile = "local-kylin"

构建适配器并执行诊断：

bash scripts/build_kylin_vector_adapter.sh
./run.sh config --json
./run.sh doctor

诊断结果应包含：

profile: local-kylin
embedder: kylin_triton
embedding_dims: 1024
vector_store: kylin_vector_engine

将配置应用到常驻服务并启动对话：

./run.sh service apply
./run.sh status --json
./run.sh run --agent memory-chat

本地 profile 使用 DeepSeek 完成回答生成和记忆事件提取，因此仍需配置 DEEPSEEK_API_KEY。

独立验证命令：

.venv/bin/python scripts/kylin_vector_smoke.py
AGENT_MEMORY_PROVIDER_PROFILE=local-kylin \
  .venv/bin/python scripts/kylin_memory_smoke.py

恢复默认链路：

[provider]
profile = "cloud-default"

./run.sh service apply
./run.sh status --json

2.7 UKUI 桌面功能

平台安装会部署 Peony 插件、桌面动作包装器和设置入口。安装后重新打开 Peony，右键本地 UTF-8 .txt 或 .md 文件即可使用“记入 AI 偏好”和“遗忘相关记忆”。

./run.sh desktop doctor --json
./run.sh desktop demo --no-notify
./run.sh desktop settings
./run.sh desktop notify --event desktop.test

插件不注册 MIME handler，不改变文件默认打开程序。文件内容经过类型、大小、编码和符号链接检查后，通过 Unix Socket 发送给 Memory Service；遗忘操作按 document_id 精确执行。

2.8 测试与演示命令

查看公开 Agent：

./run.sh agents

记忆功能测试：

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

系统集成正式链路检查：

./run.sh demo

系统集成数据集测试需要 root/BPF 权限，并使用独立临时目录：

sudo ./run.sh system-test

30 轮正式稳定性测试：

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

Python 测试：

.venv/bin/python -m pytest -q
.venv/bin/python -m pytest -m integration -v
.venv/bin/python -m pytest -m real_api -v

3. 架构设计

3.1 总体分层

Agent / Peony / 测试数据集
            |
            v
run.sh -> agent_entry.py -> RuntimeCoordinator
            |
            v
SocketMemoryService === Unix Socket === MemoryServiceRuntime
                                           |
                 +-------------------------+------------------+
                 |                         |                  |
                 v                         v                  v
          ManagerMemoryService        AuditRuntime       Provider Profile
                 |
                 v
             MemoryAPI
                 |
      +----------+-----------+
      |                      |
      v                      v
  mem0 / Vector Store      SQLite
  正文与向量              版本、行为、墓碑、审计

systemd user service -> cgroup v2 资源边界
systemd root service -> eBPF Guard -> data/ 文件访问保护

3.2 本地 C/S 运行模式

Memory Service 常驻并持有唯一 Memory Manager、SQLite 连接和所选 Vector Store。Agent 作为客户端通过权限为 0600 的 Unix Socket 提交 JSON Lines RPC。服务端通过 SO_PEERCRED 校验调用方 UID，并使用固定线程池处理读取和生成请求；记忆写入与遗忘通过同一写锁串行执行。

该结构实现：

• 多个 Agent 共享一个本地后端，不直接竞争数据库文件锁。
• Agent 退出不会关闭 Memory Manager 或影响其他客户端。
• Provider、Audit、scheduler 和数据库连接由服务端统一管理。
• systemd 能够稳定识别、重启、计量和限制记忆服务。
• eBPF Guard 可以使用服务 cgroup 作为可信文件访问身份。

3.3 统一入口与 Agent 注册

agent_entry.py 是统一 Python 入口，负责：

• 加载 .env 和 config.toml。
• 解析 Provider profile 并输出运行摘要。
• 从 AgentSpec 注册表选择 service、isolated 或 system-test 执行类型。
• 管理常驻服务、Agent 生命周期、退出顺序和错误码。
• 分发配置、诊断、服务、Guard、桌面、测试与安装命令。

Agent 只依赖 AgentMemoryService 协议，不访问 SQLite、Qdrant、mem0 client 或 Provider SDK。新增 Agent 的注册和接口规范见 agents/README.md。

3.4 组件职责

目录	职责
launcher/	入口编排、Provider profile、Unix Socket 服务、systemd/cgroup 和安装管理
agents/	交互式 Agent、记忆评测 Agent 和系统测试 Agent
memory_manager/	记忆写入、管理、生命周期、遗忘、检索和文档 RAG
mem0/	本地 mem0 运行时及 LLM、Embedding、Vector Store 适配
provider_adapters/	openKylin Vector Engine C++ 命令适配器
audit/	平台审计、Journald sink、JSONL 哈希链和 auditd 管理
ebpf_guard/	eBPF LSM、Guard daemon、cgroup 授权和状态通道
desktop_integration/	Peony 菜单、文档 Bridge、UKUI 通知和设置入口
tests/	平台、Provider、审计、Guard 和入口测试

4. 记忆层设计

4.1 写入链路

MemoryAPI.insert() 接收带有 user_id 和 session_id 的输入，按以下顺序处理：

输入规范化
  -> 文本清洗
  -> 质量校验
  -> 敏感信息 block/redact
  -> LLM 结构化事件提取
  -> 事件路由
  -> 分类管理、行为聚合或精准遗忘
  -> mem0/Vector Store + SQLite

写入事件包括：

事件	处理方式
偏好	根据稳定 key、证据优先级和语义关系创建、更新或保留冲突版本
知识	保存事实性知识和可复用 procedure
情景	按重要性、事件时间和留存策略写入会话或用户级记忆
行为	按行为签名聚合，达到跨会话阈值后晋升为偏好
遗忘	检索候选、验证主题锚点并删除明确匹配项

4.2 检索与上下文构建

查询扩展
  -> Vector Store 召回
  -> user/session/tier/status 过滤
  -> tombstone 与敏感状态过滤
  -> 语义、类型、证据、置信度、新鲜度和层级重排
  -> 偏好冲突消解
  -> 文档 chunk 与相邻块扩展
  -> 结构化上下文

普通记忆类型固定为 preference、knowledge 和 episodic。文档 chunk 使用独立类型，只通过文档检索链路进入上下文，避免与普通记忆重复召回。

4.3 生命周期与精准遗忘

• short_term：会话级短期记忆，根据访问和任务关联晋升。
• mid_term：稳定偏好、知识和重要情景，根据证据、置信度和访问频率晋升。
• long_term：同一用户下跨会话共享的长期记忆。
• TTL 以 last_accessed_at 为依据，过期记录保留状态和版本链。
• 精准遗忘只删除明确匹配项，歧义候选继续保留。
• tombstone 和 status="forgotten" 共同阻止已遗忘内容重新召回或晋升。

4.4 身份与数据隔离

外部请求必须携带：

字段	作用
user_id	用户身份
agent_id	Agent 稳定身份，由 AgentSpec.memory_agent_id 提供
session_id	当前对话或任务会话

服务端根据 user_id + agent_id 生成稳定内部 namespace。不同用户和不同 Agent 默认隔离；同一用户、同一 Agent 的长期记忆可跨 session 共享。隔离通过记录字段、Provider 过滤和内部 namespace 实现，不需要为每个 Agent 创建独立数据库进程。

4.5 存储与 Provider

存储	内容
所选 Vector Store	记忆正文、文档 chunk、Embedding 和检索 metadata
SQLite	行为统计、版本链、生命周期状态、tombstone、业务审计和文档映射

Provider profile 在 Memory Manager 构造前完成解析和检查。collection 名称绑定 Embedding Provider 与向量维度，避免 1024 维和 2048 维向量进入同一空间。入口、doctor 和常驻服务共用 memory_manager.AppConfig，不会维护第二套运行配置。

Memory Manager 详细说明见 memory_manager/README.md。

5. 系统集成功能设计

5.1 systemd 与 cgroup v2

kylin-memory.service 作为 systemd user service 持有 Memory Manager。安装器根据 config.toml 生成 service unit 和资源 drop-in：

~/.config/systemd/user/kylin-memory.service
~/.config/systemd/user/kylin-memory.service.d/50-resources.conf

cgroup 配置覆盖 CPU quota、MemoryHigh、MemoryMax、TasksMax 和 IOWeight。状态接口读取 memory.current、memory.peak、cpu.stat、memory.events 和 pids.current，形成与记忆服务对应的资源指标。

配置示例：

[runtime.cgroup]
enabled = true
profile = "desktop"
cpu_quota = "100%"
memory_high = "auto"
memory_max = "auto"
tasks_max = 256
io_weight = 100

5.2 eBPF LSM 文件保护

kylin-memory-guard.service 以 root 身份独立运行。Guard 自动发现 kylin-memory.service 的 cgroup inode，将其写入 allowed_cgroups，再注册 data/ 目录及文件 inode 并启用 enforcement。

内核 hook：

Hook	保护操作
file_open	读取、覆盖、追加和截断
inode_unlink	删除受保护文件
inode_rename	移动受保护文件或覆盖受保护目标

Memory Service 重启后，Guard 根据 service 名称重新发现 cgroup 并刷新授权。Guard daemon 周期扫描保护目录，把 SQLite WAL/SHM、Qdrant segment 等运行期新增 inode 注册到 BPF map。阻断事件写入独立归档，并通过 root-owned 状态文件向平台报告 attached/enforcing/degraded、hook、阻断计数和授权 cgroup。

详细说明见 ebpf_guard/README.md。

5.3 Audit、Journald 与 auditd

平台应用审计和系统审计分层运行：

Memory RPC / Provider / Runtime
  -> AuditEvent v1
  -> 隐私过滤
  -> AuditDispatcher
  -> JSONL 哈希链 + Journald

Linux kernel
  -> auditd
  -> 平台配置与 Guard 文件变更记录

MemoryServiceRuntime 持有唯一 AuditRuntime。事件带有 service_instance_id/request_id，主体标识使用 HMAC 稳定散列，正文、Embedding、API Key 和任意 metadata 不进入平台归档。JSONL 使用单 writer 和哈希链；Journald 用于系统查询和实时观察；auditd 监控 config.toml、Guard 配置和 root-owned Guard 代码。

常用查询：

journalctl SYSLOG_IDENTIFIER=kylin-memory -f -o cat
sudo auditctl -l | grep kylin_memory
systemctl status auditd --no-pager

详细说明见 audit/README.md。

5.4 UKUI 桌面联动

Peony 右键菜单
  -> C++ MenuPlugin
  -> DesktopBridge
  -> 文件校验与 UTF-8 读取
  -> SocketMemoryService
  -> 文档写入或精确遗忘
  -> UKUI 桌面通知

桌面 Bridge 只接受规定大小以内的本地 .txt/.md 普通文件，并拒绝符号链接、MIME 不匹配、非法 UTF-8、NUL 和空文件。原始路径转换为稳定来源 URN，文档内容进入文档 RAG 子系统，通知只携带清洗后的文件名、数量和固定事件类型。

详细说明见 desktop_integration/README.md。

5.5 系统集成验证

./run.sh demo 面向常驻服务真实链路，验证服务 cgroup 被 Guard 放行，同时验证同 UID、不同 cgroup 的外部进程被阻断。

sudo ./run.sh system-test 使用独立临时数据和 transient systemd service，默认连续执行 3 轮 eBPF、Audit、Journald 和 cgroup 测试。使用 --rounds 30 可执行 30 轮正式稳定性测试；参数范围为 1 至 30。测试覆盖：

• 普通文件访问和受保护文件授权访问。
• 绝对路径、相对路径、符号链接、追加、截断、删除和移动。
• 多进程并发访问和运行期文件注册。
• 阻断审计完整率与 Journald 送达率。
• CPU 限流、MemoryHigh、内存峰值和任务数。
• 每轮资源清理和聚合 JSON 报告。

系统测试说明见 agents/os-test/README.md。

6. 参考资料

类型	资源
mem0	mem0ai/mem0
DeepSeek	DeepSeek 开放平台
智谱 Embedding	Embedding-3 文档