MemoryOS-OK

面向 OS Agent 的多源融合偏好与知识记忆系统 Multi-Source Agentic Memory for OS Agents — Operations Kit for openKylin

让 Agent 的记忆像操作系统一样可被管理 —— 可整合、可仲裁、可追溯、可遗忘。

Give the OS Agent a memory that can be governed: integrated, arbitrated, traced, and forgotten.

初赛材料 / Submission

本仓库对应第三届中国研究生操作系统开源创新大赛社区赛题 “面向 openKylin 的智能体记忆提取与精准遗忘机制”。仓库根目录提供：

项目说明书.pdf / 项目说明书.docx：设计、实现、实验结果与证据边界；
演示PPT.pptx：openKylin 赛题专用答辩材料；
演示视频.mp4：226 秒字幕演示，低于 5 分钟与 100MB 限制；
作品原创承诺书_待手写签署.docx：组委会模板，须由参赛队员手写声明并补队伍名称、日期后替换为正式签署版。

参赛主体为中国科学技术大学，队伍名为 MemoryOS-OK Team；指导教师与学生姓名仍须按报名系统审核信息写入最终签署材料。能力状态以 openKylin 赛题逐项评分矩阵和三轴真值登记为准：包装完整不代表赛题要求或产品化已经全部闭环。

这是什么 / What

MemoryOS-OK 是为操作系统级智能体（OS Agent）设计的记忆中间件。它把”工具调用执行结果、用户行为、手动配置”三类数据源融合成一套可进化、可审计、可遗忘的长期记忆，让 OS Agent 真正记住用户的操作习惯、输出风格与安全策略，并在跨场景中精准复用。Conductor 可在推理链中主动预取相关记忆、淘汰临时上下文，并按映射清理推理缓存。默认遗忘入口现已通过可恢复 Saga 级联事件、短中长期记忆、偏好历史、安全 mmap、检索索引、Prompt Segment、Cache Key 与已登记运行时 Slot；任一必需层残留时失败关闭，不签发成功证明。

本项目面向 openKylin 社区赛题交付，同时作为长期开源研究原型维护。

为什么 / Why

现有 Agent 记忆方案在 OS 场景下都”水土不服”：

方案	冲突处理	端侧 ≤500ms	版本化/溯源	工具结果一等公民
Mem0	❌ 无机制	⚠️	❌	⚠️
Letta / MemGPT	⚠️ 丢给 Agent	❌ 慢	⚠️	⚠️
Memanto (2025)	✅ 有雏形	❌ 仅云端	✅	❌
MemoryOS-OK	✅ 三层级联 mini 95%	✅ 官方 SDK 默认全链 29.040ms；CrossEncoder 对照 4882.942ms	✅ 加密偏好历史 + checkout/diff/rollback + 来源 ID	✅

差异化组合：冲突级联、来源 ID 与哈希历史、工具结果一等公民、OS 审计和有范围边界的删除证明。首轮外部系统成对基线已完成：同一 60 题、同一原始 session 与同一 embedding 下， MemoryOS-OK / Mem0 OSS raw-memory 的 Recall@5 为 88.33% / 95.00%，精确双侧 McNemar p=0.125，不宣称统计优越。完整 LLM 记忆抽取、Letta/Zep 与端到端 QA 仍是后续证据缺口。

核心创新 / Key Features

🤝 五职能记忆 Agent + 独立 Conductor — Curator（多源整合）/ Sentinel（隐私遗忘）/ Profiler（偏好提取）/ Sage（冲突仲裁）/ Recall（关联检索）由轻量编排器治理；Conductor 独立负责推理记忆调度。
⚖️ 三层级联冲突仲裁 — L1 规则 → L2 语义 → L3 本地 LLM。当前 20 题 mini 集分布为 L1/L2/L3 = 14/5/1，正确率 95%；真实业务分布和本地 LLM P95 待扩规模复验。
🔍 可解释偏好版本链 — 偏好保存来源事件 ID，AES-GCM 加密的 append-only 历史支持 history/diff/checkout/rollback；完整 EPP 图查询仍是研究增强项。
🗑️ 自然语言驱动的统一遗忘 — “忘记我去年 4 月的所有合同细节” → 先持久化目标和删除前 Merkle 证明，再级联事件、短中长期层、偏好历史、索引、安全 mmap 和已登记推理状态；失败可恢复且不会误报成功。
🎛️ 推理感知记忆调度 — 独立 Conductor/运行时实验已实现 segment_id -> memory_id -> cache_key 映射、稳定语义前缀编译、真实 llama.cpp Prompt Cache 与 Slot 定向淘汰。
📦 端侧全栈 — 官方麒麟文本向量化 C ABI / BGE ONNX / Hash 三级后端 + sqlite-vec + 本地 Qwen3；openKylin 2.0 SP2 KVM 已完成官方 SDK 离线实测，<450MB 仍是尚未闭合的完整栈产品目标。

性能指标 / Benchmarks

指标	题目红线	实测 / 目标	状态
冲突处理正确率	≥88%	95%	✅ 20 题 mini（BGE ONNX + 确定性 Mock LLM 门禁）
知识检索召回	≥85%	94.8%	✅ LongMemEval-S 原始全量 500 题（混合检索 Recall@5，Linux L2-GPU 仅作质量证据）
检索 P95 延迟	≤500ms	29.040ms / 4882.942ms	✅ 前者为 openKylin 离线官方 SDK + sqlite-vec + BM25/RRF + 默认轻量 rerank；后者是显式 CrossEncoder 历史对照，不作为端侧默认
偏好提取准确率	≥85%	100%	✅ 16 题 mini 方向验证；规模集待扩展
完整 BGE 栈常驻内存	—	约 890MB	🟡 未达 <450MB 产品目标；需精简运行时/接麒麟 SDK
推理缓存机制峰值 RSS	—	235.57MiB	✅ openKylin L3，135M Q8 机制实验
Qwen3-0.6B 推理峰值 RSS	—	923.575MiB	🔴 openKylin KVM 三轮消融均值；完整离线链路不满足 <450MiB 目标
组件级运行时缓存淘汰	—	100%	✅ 独立 Conductor/llama.cpp 实验；openKylin L3，Slot 残留状态明确
llama.cpp Prompt Cache 命中率	—	100%	✅ 官方 Qwen3-0.6B，openKylin L3 三轮，300 Case / 900 请求
Stable Prefix Token 复用率	—	94.68%	✅ 三路因果消融，三轮 300 Case / 2700 请求
Stable Prefix TTFT P95	—	208.34ms	✅ 相对 priority-only 配对减少 263.60ms
Qwen3-4B Stable Prefix TTFT P95	—	815.21ms	✅ 普通 Linux L2 单轮 100 Case / 900 请求；相对 priority-only 配对减少 1179.95ms
Qwen3-4B 推理峰值 RSS	—	4477.852MiB	🔴 普通 Linux L2；仅推理进程，4B 不适合作为 <450MiB 默认配置

📊 检索召回在业界标准基准 LongMemEval（Mem0/Letta/A-MEM 的硬基线）上实测，非自建数据集—— 详见 docs/eval-longmemeval.md 与 500 题机器报告。原始全量 500 题上 vector-only / hybrid Recall@5 为 94.2% / 94.8%，95% Wilson CI 分别为 [91.79%, 95.93%] / [92.49%, 96.43%]；逐题精确双侧 McNemar p=0.607，因此 +0.6pp 只作为点估计，不宣称统计优越，详见全量成对比较。该全量运行使用 Ubuntu+A40 只扩展检索质量覆盖；其 19.596ms P95 不作为端侧延迟证据。端侧延迟仍引用 macOS CPU 60 题复跑的 94.561ms，且不外推目标 OS。冲突处理见 docs/m2-verification.md。与 Mem0 OSS 2.0.14 的 retrieval-only 成对系统基线见 docs/system-baseline-mem0.md：MemoryOS-OK / Mem0 Recall@5 为 88.33% / 95.00%，查询 P50 为 37.527 / 167.169ms，P95 为 311.761 / 316.023ms；p=0.125，仅支持点估计和失败归因，不支持优越性主张。完整 LLM 模式、Letta/Zep 与偏好规模评测将随 MemBench-OK 补全。

架构 / Architecture

三源输入 ──► [Curator] ──► [Sentinel] ──┬──► [Profiler] 偏好提取
工具结果              清洗/标准化  PII检测  │
用户行为                                  ├──► [Sage] 三层冲突仲裁
手动配置                                  │
                                          └──► 常驻单写者 (Unix socket + 0700/0600)
                                                    │
                                          JSONL/JSON 当前头 + 安全 mmap 副本
                                          偏好/知识加密 append-only 历史
                                                    │
短期(KV+Window) ─► 中期(原子持久化 7d Buffer) ─► 长期 ─► [Conductor] 统一 RAG 上下文
                                                         ├► [Recall] sqlite-vec/NumPy + BM25
                                                         └► Saga 统一遗忘 + Merkle proof

详见 docs/architecture.md。

openKylin 的适配边界、系统机制与目标机证据见 docs/openkylin/README.md 和 docs/openkylin/os-integration.md。

快速开始 / Quick Start

安装

git clone <本仓库 Git 地址> memoryos-ok && cd memoryos-ok
pip install -r requirements.txt
pip install -e .          # 可选：提供全局 memos 命令

命令行用起来

# 记住知识/偏好（自动 PII 过滤 + 冲突仲裁）
./memos remember "我偏好用 ripgrep 而不是 grep 搜索文件"

# 喂入工具调用事件（积累后自动捕捉偏好）
./memos observe '{"tool":"rg","exit_code":0,"user_action":"accept"}'

# 语义检索
./memos recall "搜索文件用什么工具"

# 查看捕捉到的偏好
./memos prefs

# 查看、比较、只读检出和回滚偏好版本
./memos pref-history output:style
./memos pref-diff output:style 1 2
./memos pref-checkout output:style 1
./memos pref-rollback output:style 1

# 自然语言遗忘（默认仅预览；--yes 执行并生成 Merkle 删除证明）
./memos forget "忘记关于邮箱的一切"
./memos forget "忘记关于邮箱的一切" --yes

# 未完成事务在修复运行时后显式恢复
./memos forget-resume forget_xxx

# 经验包：加密导出 + 导入（老师傅经验传承 / 团队知识共享）
./memos export experience.mpack --types workflow,case --password team
./memos import experience.mpack --password team

./memos stats

记忆默认持久化到 ~/.memoryos，跨会话存活。设 MEMOS_LLM_API_KEY 启用 LLM 增强（冲突仲裁 / 安全策略提取），不设或加 --no-llm 则走纯本地规则 + 统计，依然可用。 CLI 默认优先连接同一工作区的常驻单写者，未启动时仅为单进程开发兼容而回退。多客户端或 systemd 部署应先运行 ./memos serve，并设置 MEMOS_REQUIRE_DAEMON=1 使连接失败时直接报错，禁止静默退回多进程直写。

MEMOS_WORKSPACE="$HOME/.memoryos" ./memos serve
MEMOS_REQUIRE_DAEMON=1 ./memos remember "只允许守护进程提交"

Python API

from memoryos.core import MemoryOS

mem = MemoryOS("~/.memoryos")
mem.remember("我偏好简洁的输出风格")
hits = mem.recall("输出风格")          # → 关联检索
context = mem.recall_context("输出风格")  # → 统一 RAG 上下文，不触发模型生成
prefs = mem.preferences()              # → 捕捉到的偏好
proof = mem.forget("忘记X", confirm=False)  # → 遗忘 + 删除证明

接入 Claude Code / Codex（MCP）

内置零依赖 MCP server，让你的 AI 助手直接拥有跨会话记忆与偏好：

claude mcp add memoryos --env MEMOS_WORKSPACE=$HOME/.memoryos -- "/绝对路径/memos" mcp

接入后获得 16 个记忆工具，包括统一 RAG、4 个偏好版本工具、4 个知识版本工具、 forget / forget_resume / stats。MCP 进程与 CLI 一样优先连接常驻单写者。详见 docs/mcp-integration.md。

竞赛评测一键复现

# 单测 + openKylin 赛题评测 + 脚本语法检查
bash scripts/run_competition_checks.sh

# 仅刷新指标总表
python3 eval/eval_all.py

# 采集演示视频录屏素材
python3 scripts/capture_demo_artifacts.py

# 生成 openKylin 赛题字幕版演示视频
python3 scripts/render_demo_video.py --competition openkylin

# 生成麒麟/openKylin 适配证据快照
python3 adapt/kylin_evidence.py

# 生成远程 CPU/openKylin 目标机验证计划（默认 dry-run + safe rsync）
python3 scripts/remote_kylin_verify.py --host "$REMOTE_HOST" --user "$REMOTE_USER" --port "$REMOTE_PORT" --identity "$SSH_KEY" --remote-dir "$REMOTE_DIR" --mode ci --bootstrap-venv

# 生成研究生操作系统大赛 openKylin 社区赛题提交包
python3 scripts/build_submission_bundle.py --competition openkylin

# 扫描提交包中的本机路径、SSH 私钥路径和工作指令文件
python3 scripts/check_submission_safety.py

# 汇总检查评测、目标系统证据、视频、素材和提交包是否齐备
python3 scripts/check_submission_readiness.py

# 审计 mini 数据是否具备正式金标资格；当前会诚实返回 regression_only
python3 scripts/check_evaluation_truth.py
python3 scripts/check_evaluation_truth.py --require-gold

# 生成本机依赖指纹、CycloneDX SBOM 与许可证清单
python3 scripts/generate_supply_chain_evidence.py

# 真实 llama.cpp 冷/热 Prompt Cache 实测
MODEL_PATH=/path/to/model.gguf CASES=100 bash scripts/run_llama_prompt_cache_bench.sh

生成的统一证据入口：

eval/reports/latest.md：openKylin 赛题快速评测总表；
eval/reports/latest.json：保留每个评测脚本的原始 stdout，便于复核。
eval/reports/baselines/latest.md：vector-only / BM25-only / hybrid 轻量消融报告，后续 Mem0 / Letta / Zep 对比沿用该 schema。
docs/system-baseline-mem0.md：MemoryOS-OK 与 Mem0 OSS 2.0.14 的 60 题外部系统成对基线，包含依赖锁、embedding canary、McNemar 检验、四个失分案例与证据边界。
eval/reports/system_baselines/comparison/latest.md：外部系统成对比较摘要；逐系统逐题结果保存在同目录 JSON。
eval/reports/reasoning/latest.md：推理感知记忆评测，覆盖预取命中率、遗忘残留率、上下文构建延迟和审计覆盖率。
eval/reports/truth-gate/latest.md：评测集真值门禁；当前 mini 集被明确标记为 regression_only，不会冒充双标注、裁决完成的正式金标集。
supply-chain/latest.md：本机依赖、CycloneDX SBOM 与许可证证据；当前为 partial，因为尚无跨平台制品哈希锁和带日期的漏洞数据库审计。
eval/reports/llama_prompt_cache/local-macos.md：30 Case / 90 请求的真实 llama.cpp L1 探索性报告，含 TTFT、Prompt Eval、Token 复用与 Slot 遗忘；不替代 openKylin L3 证据。
eval/reports/llama_prompt_cache/linux-cpu.md：100 Case / 300 请求的 Linux CPU L2 verified 报告；Warm Same TTFT P95 38.26 ms、Warm Changed Suffix TTFT P95 74.14 ms、Slot 遗忘成功率 100%。
eval/reports/llama_prompt_cache/linux-cpu-resource.md：去路径化的 L2 资源摘要；本次 135M 机制验证峰值 RSS 为 245.54 MiB。
eval/reports/llama_prompt_cache/openkylin.md：openKylin 2.0 SP2 CPU-only L3 verified 报告；100 Case / 300 请求，Warm Same TTFT P95 31.21 ms、Warm Changed Suffix P95 51.75 ms、Slot 遗忘成功率 100%。
eval/reports/llama_prompt_cache/openkylin-repeated.md：135M Q8 三轮、300 Case / 900 请求的重复性证据。
eval/reports/llama_prompt_cache/openkylin-qwen3-0.6b-repeated.md：官方 Qwen3-0.6B Q8_0 的 openKylin L3 三轮复验；Warm Same / Changed Suffix TTFT P95 跨轮均值为 55.58 / 66.09 ms。
adapt/reports/openkylin-l3/llama-qwen3-0.6b-resource-summary.md：第 1 轮 Qwen3 伴随采样峰值 RSS 919.805 MiB、无 swap，并明确当前完整离线链路未达 <450 MiB。
docs/prompt-cache-ablation.md：随机排序、仅优先级排序、稳定前缀三路因果消融方法与结果；机器可读聚合见 eval/reports/llama_prompt_cache/ablation/openkylin-qwen3-0.6b-ablation-repeated.json。
eval/reports/llama_prompt_cache/ablation/linux-cpu-qwen3-4b-run1.json：Qwen3-4B Q4_K_M 的普通 Linux L2 单轮尺度复验，100 Case / 900 请求；不替代 openKylin L3。
adapt/reports/linux-cpu/qwen3-4b-run1-resource.json：Qwen3-4B L2 推理资源证据，峰值 RSS 4477.852MiB、无 swap。
adapt/reports/openkylin-l3/prompt-cache-ablation-resource-summary.md：三轮推理后端资源聚合，峰值 RSS 均值 923.575 MiB、无 swap。
adapt/reports/openkylin-l3/verification-summary.md：目标 OS KVM 验证摘要，汇总工程、OS、检索、SmolLM 与 Qwen3 目标模型三轮重复实验。
demo/artifacts/：录屏素材日志与素材清单。
演示视频.mp4：openKylin 社区赛题 226 秒字幕版演示视频。
adapt/reports/local/latest.md：当前开发机适配证据快照。
adapt/reports/remote/latest.md：远端 Linux CPU-only L2 适配证据快照。
adapt/reports/openkylin-l3/latest.md：openKylin 2.0 SP2 目标 OS KVM L3 历史 OS 能力快照。
adapt/reports/kylin-sdk/latest.md：最新 openKylin L3-SDK 断网实库证据，目标机 321/321 测试、14/14 OS 检查，默认完整检索链路 P95 29.040ms。
docs/system-hardening-evidence.md：常驻单写者、统一遗忘、偏好历史、BPF LSM 与目标平台五项闭环的实现状态和独立证据边界。
adapt/reports/bpf-lsm/linux-l2/latest.md：BPF LSM 当前为 Ubuntu 物理机 compiled 证据；活动 LSM 不含 bpf，未签发挂载或拦截结论。
adapt/reports/target-platform/ubuntu-x86_64-physical-1h-l2/latest.md：通用 Ubuntu x86_64 物理机 3600.2 秒、7199 轮真实记忆工作负载长稳；零崩溃、零确认写入丢失、零普通/mmap 残留。该证据不替代银河麒麟 V10、Linux ARM64 或功耗。
远程目标机验证计划：仅作为本地工作文件生成，不随提交包分发。
docs/reasoning-memory.md：Conductor 与 Reasoning Memory Plane 设计。
build/submission/openkylin/：openKylin 社区赛题提交目录与 .tar.gz 压缩包。
scripts/check_submission_safety.py：最终提交包安全扫描，防止本机路径和工作指令文件入包。
docs/openkylin/scorecard.md：按赛题原文逐项映射实现、证据、评分边界和冲刺顺序。
docs/readiness-truth.json：包装、赛题要求、产品化三轴机器真值登记。

平台支持 / Platforms

平台	向量后端	状态
openKylin 2.0 SP2	sqlite-vec（10 万向量微基准 P95 103ms）	✅ KVM CPU-only L3 验证
Ubuntu Linux	sqlite-vec（万级个人记忆达标；百万级需 ANN 后端）	✅ 远端 CPU-only L2 验证
macOS	NumPy fallback（仅开发与功能验证）	✅ 已验证，不作为目标 OS 证据

嵌入/LLM 均走抽象层，远程（USTC/DeepSeek）与本地（llama.cpp + Qwen3）一键切换。端侧 ONNX 加速：python scripts/export_bge_onnx.py。openKylin 适配见 docs/openkylin/README.md。

项目状态 / Roadmap

M0 立项收口：架构 + 故事 + 端侧 embedding/存储 MVP
M1 骨架：自研编排器 + 版本化(Merkle) + Curator + Sentinel + Recall（29 测试通过）
M2 命门：Sage 三层仲裁（真实评测 **冲突处理 95%**）+ Profiler 三路径 + LLM 抽象层
产品化 + MCP：MemoryOS 门面 + memos CLI + 跨会话持久化 + 零依赖 MCP server（接入 Claude Code）
赛题硬功能闭环：多源接入、偏好回溯、统一遗忘和官方 SDK 目标机离线链路已实现；持久中期层、规模评测和本轮 openKylin 回归仍有黄项，详见逐项评分矩阵
openKylin 关键增量：默认 mmap/COW、常驻单写者和 BPF LSM 源码已接入；BPF 挂载强制执行、V10 物理机、Linux ARM64 与功耗证据仍待目标环境
论文/商业化骨架：论文路线图 + 商业化路线图已纳入提交包与 readiness 审计
首轮外部系统基线：MemoryOS-OK vs Mem0 OSS raw-memory，60 题同源配对、版本锁、向量 canary、逐题结果与显著性检验已进入门禁
推理感知记忆：Conductor + 上下文切片 + cache mapping + reasoning 评测报告已接入门禁
真实推理缓存 Phase 2：稳定前缀编译 + llama.cpp SSE/Slot 适配 + macOS L1 + Linux CPU L2 + openKylin KVM L3 三轮重复 + 官方 Qwen3-0.6B 三轮复验 + 组件级运行时遗忘
Prompt Cache 因果消融：random / priority-only / stable-prefix 三路、三轮 300 Case / 2700 请求，配对 Bootstrap 区间方向一致
openKylin L3：321 项测试、14/14 OS/SDK 能力检查、官方 SDK 默认全链 P95 29.040ms、10 万向量 P95 100ms，Prompt Cache/资源证据已进入 openKylin 门禁与提交包
通用物理机长稳：Ubuntu x86_64 物理机连续 3600.2 秒、7199 轮真实记忆工作负载，零崩溃、零丢失、零普通/mmap 残留；不替代目标 OS
下一步：BPF LSM 目标机挂载与攻击探针、银河麒麟 V10 物理机/Linux ARM64/功耗 + Qwen3-4B openKylin 重复实验/长文本/并发复验 + 完整 LLM/Letta/Zep 基线 + 规模化 MemBench-OK + 真人旁白与系统实录版视频（见 requirements-coverage）
M3 遗忘与版本化
M4 研究生操作系统大赛提交冲刺
M5 现场答辩与系统实机优化

协议 / License

主项目代码：Apache 2.0
评测集 MemBench-OK：CC-BY 4.0

致谢 / Acknowledgements

感谢 openKylin 社区与麒麟软件有限公司提供赛题和目标系统支持。本项目部分思路受 Mem0、Letta/MemGPT、A-MEM、LongMemEval 等开源工作启发。

_{Built for openKylin · 国产操作系统 Agentic 记忆基础设施}