KylinMemGuard

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

KylinMemGuard 将工具执行结果、用户配置、交互行为和历史案例转换为可追溯、可版本化、可隔离、可检索和可遗忘的偏好与知识记忆，并在 Agent 任务规划、工具选择和结果生成时提供受控的 ContextBundle。

服务对象包括 OS Agent 开发者与集成者、openKylin 最终用户、安全管理员、审计与运维人员。它不是通用聊天机器人，不实现完整自主 Agent，不训练或修改模型参数，也不是单纯的数据库或向量库。现有 Agent 工具执行默认是 dry-run/simulated，不会把 Demo 记忆写入 openKylin 系统文件，也不会默认执行危险系统写操作。

记忆治理与系统纯净性

记忆是 Agent 可复用的偏好、知识和生命周期记录，不是操作系统文件，也不是模型参数。每条记忆保留来源、profile/dataset、用户/会话/场景作用域、版本、置信度、敏感级别和生命周期。检索出的条目先是 candidate；只有进入当前 ContextBundle 且 adopted=true 的 1 至 3 条记忆可以改变当前计划、工具选择或结果格式，其他候选只用于解释。

主链路：

MemoryEvent -> 清洗/提取 -> 版本化存储 -> 冲突/生命周期
-> BM25 + CPU 特征哈希 + mmap -> hybrid -> rerank
-> ContextBundle(candidate/adopted) -> Agent 计划/工具/模板
-> 回写 / 精准遗忘 / 审计 / 评测

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

能力事实层级

唯一规范事实：能力注册表与绑定 host/runtime/build/checksum 的证据记录。
运行时投影：GET /api/platform、GET /api/capabilities、GET /api/evidence。
生成文件：profile 对应的 capability_status.json、evidence_manifest.json。
文档和界面投影：docs/implementation_status.md、本 README 与“证据与评测”页面。

当前仓库模式为 local_workspace_only。没有 Git 元数据时显示“本地构建 {build_id}”，source_commit=unavailable，不会报错或要求连接远程仓库。

Windows 开发

约束：后端固定使用 conda jia310，前端 PowerShell 使用 npm.cmd；不使用项目 .venv，不使用已删除的 kylinmemguard 环境。Windows 后端为 127.0.0.1:8000，前端固定 127.0.0.1:5174，另一个项目可以继续占用 5173。

后端终端：

cd <PROJECT_ROOT>
.\scripts\run_dev_backend.ps1

前端终端：

cd <PROJECT_ROOT>
.\scripts\run_dev_frontend.ps1

访问 http://127.0.0.1:5174/，默认进入“Agent 演示”。项目没有登录页或鉴权页；http://localhost:5173/login 不是本项目。

测试、构建与 Demo：

.\scripts\run_tests.ps1
.\scripts\seed_demo_data.ps1
cd frontend
npm.cmd run build
cd ..
powershell.exe -NoProfile -ExecutionPolicy Bypass -File .\scripts\run_benchmarks.ps1

基准脚本使用独立临时 demo runtime，执行 100 次完整检索并输出 P50/P90/P95/P99、cache hit/miss、分阶段延迟与资源快照；进程级 ExecutionPolicy Bypass 只用于运行已审计的本地脚本，不修改系统策略。

uvicorn 和 Vite 会持续占用终端提供服务，使用 Ctrl+C 停止。strictPort=true 会在 5174 被占用时明确失败，不会漂移端口。

Demo / Production 隔离

KMG_PROFILE=demo 与 KMG_PROFILE=production 使用独立的 SQLite、data root、密钥、cache、index、mmap、backup、遗忘事务和 runtime artifacts。Windows 开发脚本显式使用 demo；openKylin 和安装模板默认 production。

production 首次启动为空，不自动 seed，不召回 Demo，不允许 Demo reset/import。
demo 数据标记 profile/dataset/batch，只使用文件整理、文档归档、网络只读诊断、删除前确认、敏感文件保护等 OS Agent 场景。
profile 是进程启动配置，不能在同一进程中无确认动态切换。

Production 数据接入

production 空状态引导用户前往“记忆治理 > 数据接入”，不会提示或自动导入 Demo。JSON/JSONL 示例与字段说明均由当前后端 MemoryEvent Pydantic schema 生成，前端不维护第二份手写契约。

字段事实源：backend/app/memory/schemas.py 与 GET /api/ingest/schema
JSON 模板：data/templates/memory_events.example.json 与 GET /api/ingest/templates/json
JSONL 模板：data/templates/memory_events.example.jsonl 与 GET /api/ingest/templates/jsonl
JSON Schema：data/templates/memory_event.schema.json
导入前预览：POST /api/ingest/preview，显示事件数量、来源、格式错误、masked 敏感命中及将生成的偏好/知识候选；只有 can_import=true 才允许确认导入。

3 至 5 分钟演示

在“记忆治理 > 数据接入”准备 os_agent_daily Demo。
在“Agent 演示”运行网络只读排查，观察最多 3 条 adopted 记忆及计划前后差异。
在“安全与遗忘”检测虚构姓名、手机号、邮箱和 Token。
对目标记忆执行 dry-run，检查范围后二次确认精准遗忘。
再次检索确认目标消失、非目标保留，并查看审计。
在“证据与评测”运行开发集评测，查看平台身份、证据 stale 状态和能力边界。

精准遗忘实现应用可验证的不可恢复删除与加密擦除，覆盖逐记忆密钥、SQLite、版本/事件、CPU 特征、mmap、缓存、受管备份和 Agent 召回路径；不声称 SSD 物理介质逐比特覆写。

openKylin 固定交接

复制到目标机：

cp -a '/mnt/hgfs/KMG-Share/KylinMemGuard/.' ~/KylinMemGuard/

后端终端（production，首次启动为空且不导入示例数据）：

cd ~/KylinMemGuard
source .venv/bin/activate
python -m pip install -r backend/requirements.txt
cd backend
export PYTHONPATH=.
export KMG_PROFILE=production
python -m pytest -q tests
python -m uvicorn app.main:app --host 127.0.0.1 --port 18080

前端终端：

cd ~/KylinMemGuard/frontend
npm ci
npm run build
VITE_PROXY_TARGET=http://127.0.0.1:18080 npm run dev -- --host 127.0.0.1 --port 5174 --strictPort

如需录制示例流程，先停止 production 后端，再启动独立 Demo 进程；profile 不能在同一后端进程内切换：

cd ~/KylinMemGuard
source .venv/bin/activate
cd backend
export PYTHONPATH=.
export KMG_PROFILE=demo
python -m uvicorn app.main:app --host 127.0.0.1 --port 18080

cd ~/KylinMemGuard/frontend
VITE_PROXY_TARGET=http://127.0.0.1:18080 npm run dev -- --host 127.0.0.1 --port 5174 --strictPort

Agent Demo 数据是隔离的示例 MemoryEvent、偏好、工作流、历史案例和安全策略。它不是模型训练数据，不是 openKylin 系统文件，也不会修改内核或桌面配置；重复准备使用现有幂等 seed API，只操作 demo 数据目录。

不要停止占用 8000 的 kytensor 或其他服务。完整预期输出、失败判断和回传清单见 openKylin 交接。特权操作不会自动执行：auditd 规则、BPF load、service 安装和系统级资源限制必须由用户在目标机确认。

评测边界

POST /api/eval/run 保存确定性开发集的偏好 Precision/Recall/F1、canonical event ID 检索 Recall@5/MRR/nDCG@5、跨语言稳定 ID 召回、冲突策略准确率、敏感 Precision/Recall/F1、cold/cache-miss/cache-hit/warm 延迟、吞吐和轻量资源统计。每次报告记录 dataset hash/version、profile、build、Top-K、采样次数、检索模式和 Python/平台信息。同一源事件的多个派生表示只对同一真值计分一次。

当前人工标注冻结区正在由人工填写，系统不会读取、修改或自动填答案。正式人工真值仍未形成，开发集不得冒充正式成绩；openKylin 首轮应用层与性能结果已经回传，OS 机制证据仍需第二次验证。

openKylin 首轮实机结果与 Stage2 边界

上传结果包 SHA-256 为 3711698394b39d6009e9e875d2732e7d5be5c4382d3c8e09dedbced211e70295。在 openKylin 2.0 SP2 上，后端 98 passed，前端 UI 8 passed，Vite build 通过；Demo 的幂等 seed、Agent 候选/采纳/计划差异、精准遗忘、清理和 production 隔离全部通过。100 请求完整基准为 P50 2.400ms、P90 22.663ms、P95 23.609ms、P99 24.004ms，cache-hit P95 2.643ms、cache-miss P95 24.004ms、吞吐 99.105 req/s。

首轮 OS 证据没有通过：mmap API 校验成功，但真实 /proc/self/maps 验证脚本因导入路径失败；systemd 用户单元未安装，journald 无结构化事件，cgroup 无服务 PID。mmap API active 不等于真实映射 verified，UKUI 包/会话环境存在也不等于插件或 D-Bus 能力 verified。Stage2 已修复路径与证据判定，并提供 scripts/run_openkylin_os_recheck.sh 和严格公开收集器，等待目标机第二次执行。

原始结果包含 47 个逐记忆密钥、3 个数据库及 runtime/backup/audit 数据，只能保留在独立私有 staging。公开证据由白名单重建并执行禁止文件、秘密、个人路径扫描；不得把原始 ZIP 复制到 Git、release 或公开验收包。

主要接口

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

发布包

Windows：

.\scripts\package_release.ps1

Linux/openKylin：

bash scripts/package_release.sh

两者共用 config/release_manifest.json 和 scripts/build_release.py，生成源码包和比赛验收包以及 .sha256 侧车。打包器检查禁止文件、秘密、个人路径、嵌套压缩包、UTF-8 文件名、Markdown 链接、Python import 和前端 build；不包含运行数据库、密钥、缓存、旧证据、完成人工工作簿或 incoming submissions。

文档入口

统一入口见 docs/README.md，功能逐项追踪见 FUNCTION_TRACEABILITY_MATRIX，配图与真实截图状态见 IMAGE_ASSET_MANIFEST。

Stage2 V2 技术事实收口（2026-07-30）

V2 脱敏证据包 SHA-256 为 2aa0ed3a776845d3d25837ecfe11caa85578fe1895fb436473368fa141f073d2，安全解压与 86 项内部校验和均通过。证据绑定 build_id=local-20260730-030254、workspace_manifest_sha256=6ea92d904c99dffc39023dcc08469fb662d85e5d5c06ccaab94636404cec540c、openKylin 2.0 SP2、production profile；source_bundle_sha256 在证据中仅为侧车占位文本，不能声称该字段已匹配。

在该证据构建上，openKylin 平台身份、backend systemd 服务、journald KMG_EVENT 和 backend service cgroup v2 归属/限制通过目标机命令、退出码和断言验证。mmap API 可访问但 production 未构建索引，真实进程映射探针返回 mmap_manifest_missing，因此不属于 verified。worker、auditd、BPF LSM、namespace 和 UKUI/D-Bus/Peony 没有同包目标命令证据。

V2 包不包含后端/前端测试、Demo 或 benchmark 原始结果，所以同一 build 的 P50/P90/P95/P99、cache hit/miss、throughput、RSS 与 CPU 均保留 null；上文首轮指标只作为历史结果，不可混作 V2 最终性能。本轮收口后的 local-20260730-133652 增加公开收集器和安装安全修复，源码清单已改变，需在 openKylin 对该收口构建重新执行固定验证后，才能继承 verified 状态。

初赛提交材料

项目说明书：DOCX / PDF
作品介绍：PPTX / PDF
原创承诺书：PDF
5分钟内演示视频：MP4
视频校验信息：DEMO_VIDEO.md
openKylin 一键启动入口：run_kylinmemguard.sh
说明书与PPT配图：docs/figures