AgentMem — 面向智能体的内存管理系统

OS开源创新大赛参赛作品 · 基于工作流感知的 KV Cache 生命周期管理与上下文优化

AgentMem 是一个面向 LLM 智能体（agent）推理过程的内存管理系统。它针对智能体推理的 长生命周期、多轮交互、工具调用、分支探索等特征，系统性优化 KV Cache 与上下文，在保证任务效果的前提下降低 GPU 显存占用、提升推理效率。

📋 赛题（高校赛题：面向智能体的内存管理系统设计与实现）

联系人：张老师 jfzhang@nudt.edu.cn · 参考资料：vLLM · llama.cpp

背景：随着基于大语言模型的智能体系统不断发展，其推理范式已由传统的单轮生成扩展为涵盖规划、执行与反思的长生命周期复杂过程。智能体频繁调用工具与外部环境，导致上下文持续增长与反复重构。相较于传统推理框架（如 vLLM）主要面向线性序列生成，智能体推理在内存使用上呈现 KV Cache 持续累积、上下文高度冗余、推理路径分支、工具调用大规模中间数据等特征，使内存管理系统面临生命周期长、结构动态、复用性要求高的挑战。

要求：基于 openEuler/openKylin/OpenHarmony 等国内主流开源 OS（或 Linux 发行版）开发；可在 vLLM/llama.cpp 等框架上扩展，支持多轮对话/工具调用/多阶段决策等智能体工作流；优化前后同硬件；基于开源大模型（Qwen/MiniCPM 等）构建可复现 Benchmark。优化方向：KV Cache 生命周期管理、分支推理内存共享、Prompt/上下文压缩、工具调用数据优化、分层内存与异构存储、异构 AI 加速硬件支持。

评分细则：

维度 (权重)	细项	分值
功能完整性 (30%)	完整实现智能体推理系统+内存优化 / 多模型多任务	60 / 40
应用效果 (40%)	显存降低+延迟优化 / 长生命周期方案 / 多框架适配	40 / 40 / 20
代码规范 (20%)	结构清晰符合开源规范 / 可复现+测试覆盖	80 / 20
文档质量 (10%)	技术方案+设计+部署+测试报告 / 逻辑清晰格式规范	50 / 50

核心创新：工作流感知的 KV 淘汰策略（复现并工程化 KVFlow, arXiv:2507.07400，无公开实现），通过 steps_to_execution 距离 + 内容优先级，让 LRU 无法感知的 Agent 工作流语义驱动淘汰决策。

✨ 特性

模块	能力
AgentWorkflowEvictionStrategy	SGLang `EvictionStrategy` 真实注册（`register_radix_cache_backend`），4 元组优先级 + 内容感知 + 共享前缀保护
AgentStepGraph	Agent 执行 DAG，O(log n) 计算 `steps_to_execution`（KVFlow 复现）
ContextCompressor	确定性 4 策略压缩（去重 → 工具描述 → 历史摘要 → 结果截断），纯标准库
ToolDataStore	SQLite WAL + LRU，大型工具结果外置，上下文仅留紧凑摘要
HiCacheController	GPU/Host/Storage 三层迁移决策（对接 SGLang HiCache）
三引擎适配	SGLang（深度）/ vLLM（APC）/ llama.cpp（HTTP slot），统一 `AgentMemoryAdapter` 协议
Benchmark	5 场景 + `nvidia-smi` 真实显存采样 + baseline(LRU) vs optimized 对比报告

🏗️ 架构（六层）

Layer 6  应用层    Benchmark · AgentRuntime · Scenarios
Layer 5  编排层    AgentStepGraph — steps_to_execution 排序位置距离
Layer 4  优化层    ContextCompressor · AgentWorkflowEvictionStrategy · ToolDataStore
Layer 3  存储层    HiCacheController — GPU/Host/Storage 三层迁移决策
Layer 2  引擎层    SGLangAdapter(★真实 backend 注册) · VLLMAdapter(APC) · LlamaCppAdapter(HTTP)
Layer 1  协议层    AgentMemoryAdapter Protocol · StepType · MemorySnapshot

详见 docs/design.md（系统设计）、docs/deployment.md（部署）、docs/benchmark.md（测试报告）、docs/api.md（API）。

🚀 快速开始

环境要求

Linux（已在 aarch64 + NVIDIA RTX 4090 验证；支持 Ubuntu/openEuler/openKylin 等）
NVIDIA GPU + CUDA 13（驱动 590+） / 或 CPU（llama.cpp 模式）
Python 3.10+

安装

pip install -e ".[sglang,benchmark]"     # 主引擎 + benchmark
# 或按需: [vllm] [llamacpp] [dev]

启动优化后的 SGLang 服务（4090）

# SGLang 启动时通过 sglang.srt.plugins 入口点自动加载我们的 agent_workflow backend
python -m agent_mem.engines.sglang_server --config configs/default.yaml
# 等价于：sglang 以 --radix-cache-backend agent_workflow 启动

运行 Benchmark（baseline vs optimized）

python -m agent_mem.benchmark.harness \
    --config configs/benchmark.yaml \
    --mode both --gpu 2 --repeats 2 \
    --output-dir benchmark_results/
# 产出 benchmark_results/report_<ts>.md（对比表）+ results_<ts>.json
# --mode all: 增加 ablation（server=agent_workflow 但 client priority=0），
#   分离压缩 vs 工作流编码的纯贡献 → baseline/ablation/optimized 三路对比

🔬 实现与验证状态

组件	代码	单测	4090 实跑	说明
核心分析层（step_graph / workflow_eviction / compressor / tool_store / hicache）	✅	✅	—	纯标准库，23 单测充分覆盖
SGLang 集成（backend 注册 + EvictionStrategy）	✅	✅	✅ 4090	F1 stub+patch 栈实跑 Qwen2.5-7B，cache_hit 46.68% 已验证
vLLM 适配（APC + cache_salt）	✅	✅	⏳ 待	A800 内核不匹配 4090
llama.cpp 适配（HTTP slot）	✅	✅	✅	当前 benchmark 数据基于此
核心创新（工作流感知淘汰）	✅	✅	✅ 4090 SGLang	cache_hit 46.68% vs LRU 0.0%（sglang engine-level）

延迟 benchmark 基于 llama.cpp（SM_89 源码编译，唯一全场景实跑引擎）；核心创新（cache_hit_rate）已在 SGLang 4090 实跑验证：agent_workflow 46.68% vs LRU 0.0%。详见 docs/benchmark.md。

📊 Benchmark 指标（赛题”应用效果”对齐）

每个场景测量：peak VRAM（nvidia-smi 50ms 采样取 MAX）、cache_hit_rate、TTFT、 latency(p50/p95)、tokens/s、saved_tokens、externalized_refs。

公平性：同模型、同 GPU、同 --mem-fraction-static、PYTHONHASHSEED=0、temperature=0、 warmup 后测量，仅替换缓存策略+压缩。

🧪 测试

PYTHONPATH=src python -m pytest tests/unit -q      # 纯标准库单测（无需 GPU）
PYTHONPATH=src python -m ruff check src/ tests/    # lint

📁 目录结构

src/agent_mem/
├── protocol.py              # AgentMemoryAdapter 协议 + 核心数据类型（标准库）
├── config.py                # 统一配置（YAML schema 与 loader 1:1 一致）
├── core/                    # 标准库分析层（step_graph/workflow_eviction/compressor/tool_store/hicache）
├── engines/                 # SGLang(backend+adapter+server+plugin) · vLLM · llama.cpp
├── runtime/                 # AgentRuntime（ReAct + 真实工具执行）· scenarios
└── benchmark/               # harness · sampler · scenarios · report
deploy/                      # Dockerfile（ubuntu-24.04-cu130 + sglang）+ 部署脚本
configs/                     # default.yaml / benchmark.yaml
docs/                        # design / api / deployment / REBUILD / references
tests/                       # unit / integration

📚 参考与出处

赛题: https://gitlink.org.cn/OSKYCX/mxzntdncglxtsjysx
KVFlow (NeurIPS 2025): https://arxiv.org/abs/2507.07400
SGLang: https://github.com/sgl-project/sglang · vLLM: https://github.com/vllm-project/vllm · llama.cpp: https://github.com/ggerganov/llama.cpp
系统设计 / 部署 / 测试报告 / API：见 docs/{design,deployment,benchmark,api}.md

License: MIT