KylinMemGuard

面向 openKylin OS Agent 的本地记忆中间件与治理控制面

KylinMemGuard 是面向 openKylin OS Agent 的本地记忆中间件与治理控制面。它从工具执行结果、用户配置、交互行为和历史案例中提取偏好与知识，在 Agent 的任务规划、工具选择和结果生成中复用这些记忆，并通过敏感过滤、精准遗忘、版本管理、审计、隔离和资源控制保证记忆安全。

服务对象是 OS Agent 开发者和集成者、openKylin 最终用户，以及系统安全管理员和审计人员。它不是通用聊天机器人，也不负责实现完整自主 Agent；现有 Agent 工具适配器默认 dry-run/simulated，不会把模拟执行描述成真实系统操作。

Why It Is Not Just a Memory Database

普通存储回答“写入和读取什么”；KylinMemGuard 还回答记忆从哪里来、为何被提取、在哪个用户/会话/场景生效、哪条记忆改变了 Agent 计划、是否含敏感信息、版本与冲突如何处理，以及遗忘后是否仍能从数据库、向量、缓存、mmap、备份或 Agent 上下文召回。

主链路：

MemoryEvent -> 清洗/提取 -> 版本化存储 -> 冲突/生命周期 -> BM25 + CPU 特征哈希向量 + mmap -> rerank -> ContextBundle -> Agent 计划/工具/模板 -> 回写/遗忘/审计

默认 LLM_MODE=rule，无需 GPU、本地大模型、API Key 或网络访问。CPU 特征哈希向量实际参与 Top-K，但不是预训练语义 embedding。

Capability Truth Source

GET /api/capabilities
GET /api/evidence
artifacts/capability_status.json
artifacts/evidence_manifest.json
implementation_status.md（由注册表生成）

Windows 测试不能替代 openKylin 证据。systemd、journald、auditd、cgroup v2、BPF LSM、UKUI/D-Bus/Peony 和 deb 安装必须在目标机执行并留证后才可标记 verified。

Quick Start on Windows

约束：后端 conda 环境固定为 jia310，前端 PowerShell 使用 npm.cmd，不使用项目 .venv，前端固定 5174，后端固定 8000。

cd <project-root>
.\scripts\run_dev_backend.ps1

另开 PowerShell：

cd <project-root>
.\scripts\run_dev_frontend.ps1

访问 http://127.0.0.1:5174/，默认进入 KylinMemGuard Dashboard/Agent 任务台。项目没有登录或鉴权页面；http://localhost:5173/login 属于另一个 Vite 项目。

等价命令：

cd backend
$env:PYTHONPATH="."
conda run -n jia310 python -m uvicorn app.main:app --reload --host 127.0.0.1 --port 8000

cd ..\frontend
npm.cmd run dev -- --host 127.0.0.1 --port 5174 --strictPort

Demo and Acceptance

.\scripts\seed_demo_data.ps1
.\scripts\run_tests.ps1
cd frontend
npm.cmd run build

推荐演示：导入 Demo -> Dashboard -> 混合/跨语言检索 -> Agent 记忆影响 trace -> 敏感检测 -> 精准遗忘 dry-run -> 二次确认 -> 遗忘验证 -> 审计 -> 评测 -> OS 证据。

精准遗忘采用“应用可验证的不可恢复删除与加密擦除”：AES-256-GCM 独立数据密钥、密钥擦除、SQLite/版本/派生事件/向量/mmap/缓存/备份清理、checkpoint/compaction 和全路径验证。项目不声称 SSD 物理介质逐比特覆写。

Evaluation

交互评测 API：POST /api/eval/run。完整基线：

bash scripts/run_benchmarks.sh

原始逐请求结果与汇总写入：

artifacts/evaluation/raw/
artifacts/evaluation/retrieval-debug/
artifacts/evaluation/summary.json
artifacts/evaluation/report.md
artifacts/evaluation/report.html

当前自动评测仍仅使用偏好、检索、敏感各 20 条确定性开发样本，不冒充独立人工真值。仓库已准备匿名双人标注候选包：偏好 100 条、检索 100 条、冲突 50 条、敏感 120 条，并补充遗忘、生命周期、跨语言和干扰样本各 30 条；这些文件当前均为未标注候选，human_truth=false，不得计入正式指标。流程见人工标注指南与标注进度。

openKylin Deployment

目标后端端口为 18080，与 Windows 开发端口分离：

bash scripts/check_env.sh
bash scripts/install_openkylin.sh
bash scripts/check_all_linux.sh
bash scripts/run_benchmarks.sh
bash scripts/collect_evidence.sh

特权能力不自动启用。auditd 使用 install_audit_rules.sh --apply；BPF 默认只探测，需人工审查后执行 verify_bpf_lsm.sh --load。详见部署与使用手册和 OS 机制设计与验证。

Main APIs

状态/证据：/api/health、/api/capabilities、/api/evidence
数据/版本：/api/ingest/*、/api/memories、/api/events、/api/versions/*、/api/conflicts
检索/Agent：/api/search、/api/retrieval/*、/api/agent/*
安全/遗忘：/api/security/*、/api/forget、/api/forget/transactions
隔离/OS：/api/namespaces/*、/api/os/features、/api/os/mmap、/api/os/dbus
审计/评测：/api/audit、/api/eval/run、/api/eval/latest

Troubleshooting

白屏：确认地址是 5174，运行 .\scripts\diagnose_frontend_blank.ps1，查看 F12 第一条红色错误。
Windows OS 能力降级：journald/auditd/cgroup/BPF/UKUI 属于 Linux/openKylin 能力，文件审计继续工作。
后端窗口不返回：uvicorn 正在持续提供服务，使用 Ctrl+C 停止。
5174 被占用：strictPort=true 会明确失败，不会漂移到其他端口。

Documentation

架构、部署、安全、评测、测试与演示文档位于 docs/。最终演示与提交收口分别参见演示录制检查清单、提交检查清单、GitLink 上传检查清单与匿名化检查清单。源码发布包脚本会排除 node_modules、运行时数据库、密钥、缓存和 artifacts。Debian 元数据位于 packaging/debian/；在 openKylin 成功构建、安装、升级、卸载并留证前，其状态保持 planned。

GitLink 原始赛题说明

以下内容原样保留自 GitLink 仓库初始 README；独立副本见 docs/CONTEST_README.md。

赛题题目：面向openKylin的智能体记忆提取与精准遗忘机制（社区赛题）

赛题说明：

智能体作为智能交互系统的核心组件，其记忆模块中的偏好记忆与知识记忆是支撑个性化服务适配、知识沉淀复用的核心载体。工具调用执行结果是两类记忆的核心数据源之一，同时记忆还来源于用户手动配置、跨场景行为数据等多类渠道。当前，操作系统在构建智体能记忆模块时面临双重挑战：一是AI算法层面：工具调用执行结果结构化不足、数据质量参差不齐，导致偏好提取（如工具选择偏好）不精准、知识沉淀不高效；另一方面，其他数据源存在用户行为捕捉不全面、跨场景数据不一致、配置版本混乱等问题，叠加形成动态偏好提取偏差、版本化管理效率低、新旧知识冲突滞后、关联检索精度有限等痛点，制约了智能体的服务智能化水平与用户体验。二是操作系统层面：记忆数据的存储、访问、隔离、审计缺乏OS级原生机制支撑；敏感信息（PII、密钥、Token等）的识别与过滤停留在应用层正则匹配，缺乏与OS安全子系统（LSM、namespace等）的深度结合；端侧资源受限场景下，记忆模块与OS内存子系统（页缓存、mmap）的协同优化空间未被充分挖掘。三是OS Agent 的记忆模块不仅需要完成偏好记忆与知识记忆的沉淀、管理和复用，还需要在真实交互过程中高效支撑检索增强生成，即 RAG 流程，随着记忆规模扩大、数据来源增多、端侧部署需求增强，传统仅依赖应用层向量检索或数据库调用的方式，容易在检索延迟、上下文构建、生成协同、资源占用和抗干扰能力等方面成为瓶颈。本选题聚焦解决以下核心问题：一是优化偏好记忆的动态捕捉与适配机制，尤其是工具调用执行结果数据源的处理，实现用户操作习惯、输出风格、安全策略等偏好的精准提取、版本化更新与跨场景复用；二是提升知识记忆的结构化整合、关联检索与冲突融合能力，强化工作流程知识、历史案例、可复用模板的高效沉淀与智能调用；三是面向 OS Agent 记忆驱动的 RAG 流程，设计系统级优化机制，在端侧或本地部署环境下实现更低延迟、更高吞吐和更稳定的记忆检索与生成能力。

赛题要求：

开发一套应用于智能体的多源融合偏好与知识记忆优化解决方案，具备偏好精准捕捉、知识智能整合、高效检索复用等核心功能，并通过 OS级机制设计体现系统创新。具体要求如下：

最终交付的代码需在openKylin操作系统版本上能够正常编译、运行和测试，鼓励在更多Linux发行版上编译、运行和测试；
构建多源数据整合模块，支持工具执行结果、用户行为数据、手动配置信息等数据的统一接入，建立数据清洗、格式标准化与质量校验机制；
构建偏好记忆动态捕捉模块，基于多源融合数据，实现用户操作习惯、输出风格、安全策略等偏好的自动提取与版本化管理，实现跨场景偏好适配与回溯；
设计知识记忆结构化整合机制，实现新旧知识冲突处理、关联检索优化、跨语言检索优化，支持英文历史案例在中文交互场景下的准确检索，支持工作流程知识、历史案例、可复用模板的结构化存储与智能调用；
将偏好记忆、知识记忆、短期记忆、中期记忆、长期记忆等纳入统一检索与生成链路，支持 OS Agent 在任务规划、工具调用、结果生成时高效调用相关记忆；
适配端侧部署需求，鼓励调用openKylin系统提供的文本向量化SDK和向量数据库SDK，设计轻量化存储方案；可调用操作系统、端侧平台或本地框架提供的文本向量化能力和向量检索能力，设计轻量化存储方案，确保检索响应延迟≤500ms，鼓励利用操作系统机制优化记忆索引加载、缓存管理、冷热数据分层、并发检索、异步 I/O、数据传输和资源调度，降低记忆检索与生成链路延迟； 敏感信息识别与精准遗忘：
集成敏感信息识别功能，至少支持以下三类模式的识别与过滤：①PII（身份证号、手机号、邮箱、姓名）；②凭据（API Key、Token、密码、私钥）；③用户自定义敏感模式（基于配置文件或自然语言指令）；
识别方案应至少结合一种 OS 级机制（如基于 Linux LSM 框架在内核上的钩子实现、基于 eBPF/BPF LSM 的审计程序等），不得仅停留在应用层正则匹配；
支持自然语言指令驱动的精准遗忘操作（如”忘记我上周关于X项目的所有偏好”），遗忘操作需可审计、不可恢复。 记忆模块需至少包含以下OS级机制中的2项及以上：
基于 LSM Hook 或 eBPF 的敏感信息访问拦截：在内核的文件系统访问、IPC调用、系统调用路径上插入安全钩子，对包含PII、密钥、Token、API凭据等敏感模式的记忆条目进行写入前拦截或脱敏；
基于 mmap + 页缓存的版本化记忆存储：基于 mmap 接口管理记忆条目存储，依赖 Linux 页缓存机制做热度管理；新旧版本采用 Copy-on-Write 机制，避免内存翻倍占用；
基于 namespace 或 cgroup 的多会话记忆隔离与资源管控：利用Linux 用户/挂载/IPC 命名空间隔离不同用户/会话的记忆空间，在OS上以 systemd user scope 或自建 daemon 形式落地；用 cgroup v2 控制记忆模块 CPU、内存资源开销，避免影响主业务的流畅性；
集成 systemd-journald 或 auditd 的记忆操作审计：所有记忆读写、版本切换、精准遗忘操作进入 systemd-journald，并通过 auditd通道写入系统审计日志，支持事后追溯与合规审查；
与 openKylin UKUI桌面环境深度联动（鼓励）：通过 D-Bus 与 UKUI 生态组件深度集成–文件管理器 peony（右键菜单注入”记入偏好/遗忘相关记忆”动作）、设置中心 ukui-control-center（注入”AI 记忆”配置面板插件）、通知守护 ukui-notification-daemon（拦截/遗忘事件的桌面通知），让记忆模块的偏好/知识能力直接服务于系统日常使用场景。
支持短期记忆、中期记忆与长期记忆之间的数据流转、沉淀、更新与淘汰机制；
设计量化评测机制，通过标准化数据集验证偏好提取准确率、知识检索召回率等核心指标，形成完整测试报告。
评分细则（明确评审角度、标准和分值范围）：
功能完整性（40%）：
多源数据整合与清洗机制：数据统一接入模块完整，清洗、标准化、质量校验机制健全；（10分）
偏好记忆动态捕捉与版本管理：偏好自动提取、动态更新、版本回溯功能完整；（25分）
知识记忆结构化与冲突处理：结构化存储、关联检索、冲突检测与融合策略可工作；（25分）
评测机制与验证：测试数据集、对比基线、报告完整；（15分）
敏感信息识别与精准遗忘：三类模式识别+精准遗忘功能完整；（15分）

OS层面深度集成：完成≥2项OS级机制得6分，每多1项+2分（上限10分,仅停留在应用层最高5分）。

性能优化（30%）：

采用分档给分方式，确保指标可衡量、可分级，重点关注偏好提取准确率、知识检索召回率、知识冲突处理正确率、检索响应延迟（P95）、敏感信息识别F1等指标。指标定义与计算方法：

指标	计算公式	测量方法
偏好提取准确率	TP / (TP + FP)	TP=正确提取的偏好条目数，FP=误提取的偏好条目数；以人工标注为真值
知识检索召回率	Top-K命中的相关条目数 / 标注相关条目总数	K=5；以人工标注为真值
知识冲突处理正确率	与人工裁决一致的冲突解决数 / 全部冲突样本数	由不少于2名标注员独立裁决，分歧样本以多数投票为准
检索响应延迟	端到端检索P95延迟（毫秒）	含embedding+向量检索+rerank全链路；不少于100次请求统计
敏感信息识别F1	2×P×R / (P+R)	P=精确率，R=召回率，针对敏感模式识别任务
模块资源占用	RSS内存峰值、CPU使用率均值	通过 /proc/[pid]/status、cgroup统计；与未启用记忆模块的基线对比

代码规范性（20%）：

代码结构与可维护性：模块划分合理，高内聚低耦合；注释完整，完全开源；（80分）
工程规范：代码风格符合开源社区规范（如命名规范、提交信息规范等），具备良好的工程化素养。（20分）
文档质量（10%）：
文档包含概要设计说明书、详细设计说明书以及部署说明等在内的完整设计文档，架构图与流程图清晰；（50分）
提供完整的部署说明文档，环境依赖、安装步骤、配置项说明清晰，可操作性强；（30分）
提供完整的测试报告，包含测试环境、测试用例、量化评测数据（准确率、召回率等）及结果分析。（20分）
交付物清单：

完整开源源代码
概要设计说明书 + 详细设计说明书
部署与使用手册（含一键安装脚本）
测试报告
3-5 分钟演示视频
赛题联系人：
韩老师 hanxinyu@kylinos.cn
参考资料：

智能体效率大揭秘：记忆、工具与规划的优化之道——当AI学会“思考”，效率成为新战场：https://zhuanlan.zhihu.com/p/1998073661610009655
Rethinking Memory in LLM based Agents: Representations, Operations, and Emerging Topics：https://arxiv.org/abs/2505.00675