AgentKV-OS

AgentKV-OS 是面向智能体推理过程的内存管理系统，对应操作系统大赛赛题 14：面向智能体的内存管理系统设计与实现。

项目目标不是实现一个普通 Agent 应用，而是在真实工具型 Agent 工作流中，对上下文、KV Cache、工具调用中间数据和分支推理状态进行系统级管理，在保证任务成功率基本不下降的前提下降低显存占用与推理延迟。

核心思路

AgentKV-OS 将 Agent 的历史上下文从线性 messages 抽象为 Context DAG，并在 Agent 语义层实现：

• Context DAG：共享 system prompt、tool schema、任务目标和公共历史节点。
• Branch Copy-on-Write：分支推理共享父上下文，只保存增量。
• Tool Result Virtual Memory：大工具结果对象化存储，只把 handle、schema、sample 和 summary 放入 prompt。
• Hot/Warm/Cold Tiering：按语义热度、生命周期和预算构造进入模型的上下文。
• Agent-aware Eviction：根据 Agent 状态而不是单纯 LRU 进行上下文降级、摘要和回收。

当前开发定位

本仓库承载 AgentKV-OS 的核心代码、评测脚本、部署文档和国产 OS 适配材料。

viper 暂作为外部 workload/benchmark substrate 接入，不直接复制进本仓库。后续可通过以下方式之一集成：

• 本地路径配置。
• Git submodule。
• 独立 adapter 包。

目录结构

AgentKV-OS/
  agentkv/              # 核心内存管理模块
  bench/                # benchmark runner 和任务定义
  configs/              # 本地、AutoDL、openEuler 配置
  deploy/openeuler/     # 国产 OS 适配部署文件
  docs/                 # 架构、开发、部署和测试报告
  scripts/              # 环境检查、启动和评测脚本
  tests/                # 单元测试和集成测试
  results/              # 本地生成的实验结果，默认不入 Git

第一阶段目标

1. 本地跑通 AgentKV-OS 的 Context DAG 和 Tool Result Virtual Memory 单元测试。
2. 使用 mock LLM 跑通 viper -> AgentKV-OS -> LLM API 的 prompt 构建链路。
3. 在 AutoDL 上接入本地 vLLM，采集 baseline metrics。
4. 在同硬件同模型下比较 baseline 与 AgentKV-OS 的显存、延迟、tokens 和任务成功率。

具体开发路线见 docs/development_plan.md。

本地开发命令

安装开发依赖：

python -m pip install -e ".[dev]"

准备真实 tokenizer 计数器。脚本只拉取 tokenizer.json，不会安装 torch 或 transformers；文件会放在 .cache/tokenizers/，不进入 Git：

scripts/setup_tokenizer.sh qwen2.5-7b-instruct

运行单元测试和 mock benchmark：

./scripts/run_unit_tests.sh
./scripts/run_mock_benchmark.sh /tmp/agentkv_mock

如果需要固定使用确定性的 whitespace 计数器：

AGENTKV_TOKENIZER=whitespace ./scripts/run_unit_tests.sh

开发原则

• 先做可评测系统，再做底层增强。
• 所有优化必须有 baseline、消融实验和指标输出。
• 不把工具原始大对象直接塞进 prompt。
• 不把 Ubuntu 路径、AutoDL 路径、模型路径写死在代码里。
• 国产 OS 适配以 openEuler 为主线。