MemGuard-Kylin

面向openKylin OS Agent的本地记忆提取、治理、检索与精准遗忘中间件。

MemGuard-Kylin位于Agent与端侧记忆存储之间，将对话、工具执行结果、用户行为、手动配置和知识文档转换为统一记忆，并提供偏好版本化、短中长期生命周期、混合检索、RAG上下文、敏感信息治理、自然语言精准遗忘和OS级安全审计能力。

TransportGPT是当前参考接入客户端，但MemGuard核心不依赖TransportGPT、LangChain或其他Agent框架。其他Agent可以通过相同的HTTP API或零依赖Python客户端接入。本项目解决的是“兼容不同Agent”，不提供多个Agent之间的任务协调或协作编排。

核心能力

多源统一接入

支持对话、工具结果、用户行为、手动配置和知识文档；
使用统一AgentEvent协议完成字段校验、来源追踪和格式标准化；
使用event_id实现幂等写入，并拒绝相同编号对应不同负载；
对正文、结构化工具结果和metadata进行递归敏感检测与脱敏。

偏好与知识记忆

提取输出语言、格式、详细程度、安全策略和工具选择等偏好；
保存偏好证据、置信度、场景、父版本和版本历史；
支持查询历史版本以及通过追加新版本完成可审计回滚；
支持知识、偏好、工具和情景记忆的统一存储与调用；
已建立知识结构化、质量治理、生命周期和遗忘验证的扩展契约，便于后续模块独立实现并统一集成。

统一检索与RAG

组合关键词、向量相似度、时间和偏好权重进行混合检索；
支持用户隔离、记忆类型过滤和短期会话隔离；
向量服务失败时可降级到关键词检索并记录审计；
构造带memory ID、引用、Token预算、截断状态和耗时的有界RAG Context；
对历史记忆正文进行边界转义，降低记忆内容伪造系统指令的风险。

敏感信息与精准遗忘

识别手机号、身份证号、邮箱、字段上下文姓名等PII；
识别API Key、Token、密码和私钥等凭据；
支持JSON配置的用户自定义敏感模式；
支持redact、block和受控测试allow策略；
支持中文自然语言遗忘指令、候选预览和一次性确认Token；
严格执行“先删除系统向量、后擦除SQLite活动内容”；
向量删除失败时中止不可逆正文擦除；
审计日志保留操作和原文哈希，不保留已遗忘正文。

openKylin与OS级机制

通过openKylin Embedding C接口生成系统文本向量；
通过C++桥接调用openKylin系统向量数据库SDK；
通过systemd用户服务部署并使用cgroup v2限制CPU、内存和任务数；
将记忆操作和服务日志写入systemd-journald；
提供BPF LSM内核程序和用户态加载器，对SQLite主库、WAL和SHM文件执行数据库文件级audit或enforce；
SQLite内部使用SHA-256链式审计记录检测历史篡改。

系统架构

TransportGPT / 其他Agent / 工具 / 手动配置 / 文档
                         │
               Agent API v1 / MemGuardClient
                         │
                         ▼
       ┌──────────────────────────────────┐
       │ 统一接入、幂等、清洗、校验、脱敏 │
       └────────────────┬─────────────────┘
                        │
          ┌─────────────┼──────────────┐
          ▼             ▼              ▼
     偏好提取       知识与质量治理     生命周期决策
          └─────────────┼──────────────┘
                        ▼
       ┌──────────────────────────────────┐
       │ SQLite权威存储                    │
       │ 版本链 / 同步状态 / 审计哈希链    │
       └────────────┬───────────────┬─────┘
                    │               │
                    ▼               ▼
       openKylin Embedding SDK   openKylin向量数据库SDK
                    └───────┬───────┘
                            ▼
              关键词＋向量＋时间混合检索
                            │
              ┌─────────────┴─────────────┐
              ▼                           ▼
       有界RAG Context              两阶段精准遗忘
              └─────────────┬─────────────┘
                            ▼
          systemd / cgroup v2 / journald / BPF LSM

更详细的设计见项目与架构说明。

Agent接入

默认HTTP地址为http://127.0.0.1:8765。Agent可以使用通用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",
)

完整协议见Agent API v1，TransportGPT的薄适配方式见TransportGPT接入说明。

本地开发与测试

项目要求Python 3.10或更高版本，核心Python包不依赖第三方运行库。

python3 -m venv .venv
source .venv/bin/activate
python3 -m pip install -e .
python3 -m unittest discover -s tests -v
python3 -m memguard.web --host 127.0.0.1 --port 8765

Windows PowerShell可以使用：

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

离线测试默认不启用生产向量后端。确定性Embedding和内存向量库仅用于测试，不能替代openKylin生产SDK。

openKylin部署

生产部署需要openKylin提供：

Embedding开发包及官方GTE模型；
系统向量数据库开发包和运行服务；
Python 3.10或更高版本；
CMake与C++编译环境；
可选的Clang、libbpf和BPF LSM内核能力。

安装脚本会检查系统SDK、构建向量桥接并安装systemd用户服务：

sudo bash deploy/install_openkylin.sh

需要同时构建BPF组件时：

sudo MEMGUARD_BUILD_BPF=1 bash deploy/install_openkylin.sh

BPF默认建议以audit模式部署。切换enforce前必须确认MemGuard服务PID白名单、数据库路径和恢复边界。详细构建方式见bpf说明。

当前进展

当前版本为0.2.0，已完成：

通用Agent API v1、Python客户端和旧API兼容；
多源事件接入、幂等、敏感治理和来源审计；
偏好提取、版本历史和回滚；
SQLite与系统向量索引同步状态管理；
混合检索、RAG Context和向量故障降级；
TransportGPT薄适配器和框架无关参考Agent；
自然语言精准遗忘和双存储删除；
openKylin Embedding与向量数据库SDK生产适配；
systemd、cgroup v2、journald和BPF LSM链路；
知识、质量、生命周期、遗忘验证和审计覆盖率的公共治理契约。

当前Windows开发基线共有51项单元与集成测试，全部通过。此前版本已经在openKylin 2.0 SP2完成31项核心测试、系统Embedding、系统向量数据库Upsert/Search/Delete、跨语言检索、精准遗忘以及OS机制验证。公开验证记录见openKylin 0.2.0验证。

上述延迟证据属于功能验收样本，不代表正式规模性能报告。当前治理契约是并行开发接口，不代表知识冲突、质量评分和生命周期评分已经接入生产流程。

正在完善

工作流、历史案例、模板等知识子类型；
来源可信度、冲突组、冲突检测与可解释裁决；
内容和语义去重、质量评分、异常隔离与跨源一致性；
偏好跨场景融合和时间衰减；
会话摘要、价值/热度/可信度评分及可解释晋升和淘汰；
WAL、旧句柄、备份和快照等精准遗忘边界；
auditd审计通道和完整读写覆盖率；
TransportGPT真实模型两轮RAG闭环；
100、1000、5000条记忆下的正式P95、吞吐和资源评测；
偏好、知识、跨语言、敏感识别和遗忘的标准化量化报告；
最新版本的openKylin全量回归和干净环境安装复现。

项目结构

路径	说明
`memguard/`	协议、服务、存储、安全、治理契约、检索、客户端和适配器
`openkylin/`	openKylin系统向量数据库SDK C++桥接
`bpf/`	BPF LSM内核程序、用户态加载器和构建入口
`deploy/`	openKylin安装和systemd配置
`tests/`	单元、HTTP、向量、Agent兼容和交付契约测试
`benchmarks/`	量化评测入口
`examples/`	框架无关Agent与业务事件示例
`docs/`	架构、API、接入和公开目标机验证记录

安全边界

仓库不应包含真实API Key、Token、密码、私钥、个人.env或用户隐私数据；
生产配置在openKylin SDK缺失时应明确失败，不能静默使用测试向量实现；
当前“不可恢复遗忘”覆盖活动SQLite内容和系统向量索引，不宣称自动删除所有离线备份、人工副本或系统快照；
BPF LSM提供数据库文件inode/TGID级访问保护，不是逐条记忆内容的内核识别；
不同client_id表示不同Agent来源，仅用于追踪与审计，不代表多Agent协作。

License

本项目采用MIT License。