MemGuard-Kylin

面向 openKylin OS Agent 的本地智能体记忆中间件，提供多源记忆接入、偏好提取、知识整合、统一检索、敏感信息保护与自然语言精准遗忘。

MemGuard-Kylin 位于 Agent 与端侧存储、向量服务及操作系统安全机制之间。项目将对话、工具执行结果、用户行为、手动配置和知识文档统一转换为可治理记忆，并通过 openKylin 系统向量 SDK、systemd/cgroup、journald/auditd、BPF LSM 和 UKUI 集成，为本地 Agent 提供可运行、可审计、可验证的记忆基础设施。

核心功能已经完成并在 openKylin 2.0 SP2 上通过源码、服务、系统 SDK、OS 安全机制和公开数据集复验。 全部说明文档网盘分享链接：https://pan.baidu.com/s/1UE3bLI_Mzo60A-SgGvFemQ?pwd=dek3，在本仓库交付文档文件夹中亦有上传。

功能概览

多源记忆接入

• 支持对话、工具结果、用户行为、手动配置和知识文档；
• 使用统一 AgentEvent 协议进行字段校验、格式标准化和来源追踪；
• 通过 event_id 保证幂等写入，拒绝编号相同但负载不一致的事件；
• 对正文、结构化工具结果和元数据执行递归敏感检测与策略处理。

偏好与知识记忆

• 提取输出语言、格式、详细程度、安全策略和工具选择等偏好；
• 保存偏好证据、置信度、场景、父版本和版本历史；
• 支持工作流知识、历史案例和可复用模板的结构化存储；
• 提供知识冲突检测、来源优先级裁决、版本替代链和可解释融合；
• 支持短期、中期和长期记忆的晋升、更新与淘汰。

统一检索与 Agent/RAG

• 融合关键词、向量、时间、记忆类型和偏好权重；
• 支持用户、客户端、会话和记忆类型隔离；
• 生成带记忆 ID、引用、Token 预算、截断状态和耗时的 RAG Context；
• 在 task_planning、tool_call 和 result_generation 三个阶段调用同一记忆链路；
• 向量后端不可用时可降级到关键词检索，并写入审计记录。

敏感信息保护与精准遗忘

• 识别 PII、API Key、Token、密码、私钥和用户自定义敏感模式；
• 支持 redact、block 和受控测试策略；
• 使用 AES-256-GCM 信封加密，记录采用独立随机数据密钥；
• 使用主密钥派生的 HMAC 盲索引缩小密文检索候选范围；
• 支持中文自然语言遗忘指令、候选预览和一次性确认令牌；
• 同步清理密文、数据密钥、盲索引、系统向量和缓存；
• 遗忘操作进入哈希链审计，并写入 journald/auditd。

openKylin 与 OS 级机制

• 调用 openKylin 文本向量化 SDK 和向量数据库 SDK；
• 使用 SQLite WAL、secure_delete、盲索引和维护任务支持加密存储、版本记录与安全回收；
• 通过 systemd user service 和 cgroup v2 管控 CPU、内存与任务数；
• 通过 BPF LSM 对 SQLite 主库、WAL、SHM 和主密钥文件进行 audit/enforce；
• 通过 auditd、journald 和应用审计链提供独立追溯证据；
• 通过 D-Bus 与 UKUI 设置入口、Peony 动作和通知组件联动。

技术实现说明

1. 事件治理与多源接入

Agent API v1 将 message、tool_result、user_behavior、manual_config 和 document 统一为 AgentEvent。写入前校验 event_id、用户/客户端/会话作用域和 结构化负载；相同 event_id 的不同负载会被拒绝。正文、工具结果和嵌套元数据递归 执行敏感扫描、脱敏或阻断，清洗后的事件才进入记忆管线。

2. 记忆模型与生命周期

偏好记录保留偏好键值、证据、置信度、适用场景、父版本和回溯链；知识记录保留 类型、主题、来源、版本、冲突状态和融合解释。SQLite 是当前版本的权威状态库， 采用 WAL 和 secure_delete，密文、盲索引、向量索引与审计引用保持一致。短期记忆 按时间和访问热度晋升为中期/长期记忆，过期或被替代的版本由维护任务淘汰。

3. 混合检索与 RAG

检索阶段组合关键词、向量、时间、记忆类型、作用域和偏好权重，并对候选进行去重、 重排和 Token 预算截断；向量后端不可用时回退到关键词检索并记录降级事件。生成的 RAG Context 包含记忆 ID、引用、截断状态和耗时，task_planning、tool_call、 result_generation 三个阶段复用同一条检索链路。

4. 加密、精准遗忘与审计

每条记录使用独立随机 DEK 进行 AES-256-GCM 信封加密，主密钥仅用于包裹 DEK 和生成 HMAC 盲索引。自然语言遗忘指令先生成候选预览，再由一次性确认令牌触发；执行时同步 清理数据库、向量、缓存、密钥材料和索引，并写入哈希链审计记录。BPF LSM 对数据库、 WAL/SHM 和主密钥文件提供 OS 级访问审计/拦截，systemd/cgroup 负责服务生命周期和 资源边界，journald/auditd 提供系统审计通道。

5. 部署边界与实现诚实性

openKylin 部署使用本地向量/Embedding SDK、systemd user service 和 cgroup v2； UKUI 通过 D-Bus、Desktop Entry 和通知接口提供设置、文件动作与事件提示。本发布版 不宣称显式实现 mmap/Copy-on-Write 记忆存储或 namespace 隔离；这两项属于后续 OS 存储与多会话隔离增强方向，不影响当前已验证的 BPF LSM、systemd/cgroup 和 journald/auditd 机制结论。

系统架构

核心数据链路：

Agent / 工具 / 手动配置 / 知识文档
                    │
             Agent API v1
                    │
      清洗、校验、敏感检测与偏好提取
                    │
     加密存储、版本治理、生命周期管理
                    │
  openKylin Embedding SDK + Vector SDK
                    │
      混合检索、RAG Context、精准遗忘
                    │
 systemd / cgroup / BPF LSM / auditd / UKUI

更完整的模块和数据流说明见架构设计。

快速开始

通用 Python 环境

要求 Python 3.10 及以上。

git clone https://gitlink.org.cn/a112334/mxokdzntjytqyjzywjz.git
cd mxokdzntjytqyjzywjz

python3 -m venv .venv
source .venv/bin/activate
python3 -m pip install -e .

python3 -m unittest discover -s tests
python3 -m memguard.web --host 127.0.0.1 --port 8765

服务启动后可检查：

curl http://127.0.0.1:8765/v1/health

Windows PowerShell：

py -m pip install -e .
py -m unittest discover -s tests
py -m memguard.web --host 127.0.0.1 --port 8765

通用开发环境默认使用本地确定性向量实现完成离线测试。openKylin 系统 SDK 和 OS 机制必须在 openKylin 环境验证。

openKylin 一键部署

生产部署需要 openKylin 2.0 SP2 或比赛指定的更新版本，并预先安装：

• python3、python3-cryptography、cmake、pkg-config；
• libkylin-coreai-embedding-dev；
• libkysdk-vector-engine-client-dev；
• openKylin GTE 模型包；
• 已登录的 UKUI 用户会话或可用的用户 D-Bus；
• 启用 BPF 时所需的 Clang、libbpf、内核 BTF 和 BPF LSM 能力。

基础部署：

sudo bash deploy/install_openkylin.sh

包含 BPF LSM 与 auditd 的竞赛验收部署：

sudo MEMGUARD_COMPETITION_MODE=1 bash deploy/install_openkylin.sh

部署后检查：

systemctl --user status memguard-kylin.service
systemctl --user status memguard-kylin-maintenance.timer
curl http://127.0.0.1:8765/v1/health

安装依赖、BPF 模式、UKUI 会话、可选模型和卸载方式见部署与使用手册。

Agent 接入示例

HTTP 服务默认监听 127.0.0.1:8765。Python 客户端示例：

from memguard import AgentEventType, MemGuardClient

client = MemGuardClient("http://127.0.0.1:8765")

client.remember(
    "设备巡检应先检查电源状态。",
    event_id="inspection-knowledge-v1",
    event_type=AgentEventType.DOCUMENT,
    client_id="example-agent",
    user_id="example-user",
    session_id="example-session",
)

context = client.retrieve_context(
    "设备巡检首先检查什么？",
    client_id="example-agent",
    user_id="example-user",
    stage="task_planning",
)

接口字段、错误码和鉴权方式见 Agent API v1。参考 Agent 和三阶段调用示例位于 examples/agent_compat/。

验证与构建

完整发布预检：

python3 scripts/verify_release.py

预检包含：

• 单元与集成测试；
• Python 编译检查；
• 核心离线评测；
• 源码空白与 Shell 换行检查；
• 隐私和敏感内容扫描；
• 确定性离线 Wheel 构建与安装验证。

仅构建离线 Wheel：

python3 -S scripts/build_wheel.py --wheel-dir .test-tmp/offline-wheel

外部公开数据集适配、正式评测协议和资源测量入口位于 benchmarks/。模型权重、原始公开数据、预测明细和运行日志不随源码发布。

最终测试摘要

验证项目	最终结果
openKylin 单元与集成测试	488/488 通过
偏好提取回归	Precision / Recall / F1 = 1.0000
PRISM 结构化偏好接入	300 条、2,700 标签，F1 = 1.0000
MultiWOZ 2.2	Recall@5 = 1.0000，P95 = 30.615 ms
ToolBench	Recall@5 = 1.0000，P95 = 48.848 ms
MKQA 中查英跨语言检索	Recall@5 = 0.9800，MRR = 0.9620，P95 = 58.001 ms
SNLI 语义关系预测	Accuracy = 0.8900
PII Bench ZH 独立验证集	Precision = 0.9701，Recall = 0.9733，F1 = 0.9717
CLUENER 与安全扩展集	F1 = 0.7857
精准遗忘	目标删除成功率 = 1.0000，误删率 = 0，向量残留率 = 0
BPF LSM/auditd 系统绑定	7/7 通过
5,000 条加密记忆系统 SDK 检索	Recall@5 = 1.0000，P95 = 61.717 ms
真实模型 Agent A/B	启用记忆准确率 = 0.9900，检索 P95 = 102.829 ms

完整测试环境、数据集、指标定义、资源占用和结论边界见最终测试报告。

文档与交付物

正式竞赛交付材料位于 交付文档/：

• 项目说明书；
• 概要设计说明书与详细设计说明书；
• 部署与使用手册；
• 测试报告；
• 答辩 PPT；
• 演示视频；
• 作品原创承诺书。

适合源码阅读和二次开发的文档：

• 概要设计
• 详细设计
• 部署与使用
• Agent API v1
• 知识冲突融合
• UKUI 集成

项目结构

memguard/       核心 Python 运行时
benchmarks/     数据适配、评测与资源测量
bpf/            BPF LSM 程序与用户态加载器
openkylin/      openKylin 向量数据库 C++ 桥接
deploy/         systemd、auditd、UKUI 与一键安装脚本
integrations/   UKUI 与外部系统集成
examples/       Agent 接入示例
config/         安全、Embedding、NER、NLI 示例配置
tests/          单元与集成测试
docs/           开发者文档
交付文档/       正式竞赛交付材料

安全与隐私边界

• 不要提交 .env、API Key、Token、主密钥、数据库、模型缓存或本机运行日志；
• 主密钥、API 令牌和状态数据库由安装器写入用户状态目录，并使用最小权限；
• “不可恢复”验证覆盖项目控制的密文、数据密钥、索引、缓存和审计输出，不覆盖宿主机快照、外部备份和第三方副本；
• BPF LSM 负责受保护文件的访问控制，不解析自然语言正文；PII 与凭据识别由应用层和可选本地模型完成；
• 可选模型只从部署方审查过的本地目录加载，核心服务不会自动下载权重。

License

项目核心代码采用 MIT License。外部公开数据集、模型和系统 SDK 受各自许可证约束，不随本仓库源码重新分发。