AgentMemOS

面向智能体长生命周期推理的内存管理中间件（操作系统开源创新大赛作品）。

作品简介

AgentMemOS 在开源推理引擎之上，以「中间件增强、引擎复用」方式管理智能体场景下的上下文、工具中间数据与逻辑 KV 驻留，形成可调度、可审计、可消融的内存控制栈，主要能力包括：

上下文布局：静态前缀与动态后缀分离，稳定跨轮 / 跨角色 Prefix Caching 命中条件；
工具数据管理：超长工具结果摘要 + 内容寻址外存（TOS）+ 按需物化，并以质量门控约束信息损失；
生命周期调度：基于步骤图的工作流打分（STE / reuse / size）替代纯 LRU，决定热层保留与换出；
分层存储：GPU（热）→ CPU（温）→ 磁盘（冷）换出、提升与预取；
压力控制与 OS 适配：统一压力控制器联调多类旋钮，对接 cgroups 等资源接口；
评测与验证：公平缓存协议下报告前缀命中、逻辑上下文 / 估算 KV、时延与任务成功率，并提供消融与负例。

本仓库包含可运行源码（agentmem/）、基准与演示脚本（benchmarks/）、单元测试（tests/）、辅助脚本（scripts/）、已固化结果日志（results/）以及说明书配图（docs/图*.png）。

提交材料

仓库根目录已包含以下参赛提交文件（未使用 Git LFS）：

文件名	说明
`参赛承诺书.jpg`	参赛承诺书
`设计文档与技术报告.docx`	设计文档与技术报告
`演示PPT.pptx`	演示幻灯片
`演示视频.mp4`	演示视频（MP4 格式，体积小于 100MB）

运行说明

环境要求

项目	建议
OS	Linux + NVIDIA Driver（GPU 主结论路径）
Python	3.10+
推理	vLLM（主路径）；可选 LMCache
模型	如 Qwen2.5-7B-Instruct（GPU 实验）；部分演示脚本可 CPU 运行
依赖	见 `requirements.txt`；CI/CPU 最小集见 `requirements-ci.txt`

安装

# 在仓库根目录执行（clone 后 cd 到本仓库）
pip install -r requirements.txt
# 仅 CPU 回归时可：pip install -r requirements-ci.txt
export PYTHONPATH=$PWD

请按本机环境自行准备 vLLM、CUDA 与模型权重路径；将下文中的模型路径替换为实际路径。

快速验证（CPU，推荐先跑）

不依赖 GPU，覆盖单元测试与轻量演示 / 基准：

# 在仓库根目录执行（clone 后 cd 到本仓库）
export PYTHONPATH=$PWD
bash scripts/ci_cpu.sh

常用单点演示：

python benchmarks/demo_tos_materialize.py
python benchmarks/demo_cgroup_online_loop.py
python benchmarks/demo_memory_timeline.py
python benchmarks/run_workflow_score_ablation.py
python benchmarks/run_negative_cases.py

GPU 主路径（需本机模型与 vLLM）

# 在仓库根目录执行（clone 后 cd 到本仓库）
export PYTHONPATH=$PWD

# 示例：布局 / 工具与分层 / 周消融（耗时视硬件而定）
python benchmarks/verify_direction_b.py --model /path/to/Qwen2.5-7B-Instruct
python benchmarks/verify_direction_c_ae.py --model /path/to/Qwen2.5-7B-Instruct
python benchmarks/run_week5_ablation.py --model /path/to/Qwen2.5-7B-Instruct

# 或一次性入口（若脚本支持）
python benchmarks/run_all.py /path/to/Qwen2.5-7B-Instruct

真多会话 batch 等可用更小模型以降低显存占用，例如：

python benchmarks/bench_real_multisession.py --model /path/to/Qwen2.5-1.5B-Instruct

具体参数以各脚本 --help 为准。

结果与图片

路径	说明
`results/*.json`	已复现实验的判定与指标日志（可直接查阅）
`results/*.png`	部分脚本生成的对比图
`docs/图*.png`	说明书 / 报告用图

重新运行基准后，对应 JSON/PNG 会写入或覆盖 results/。

目录结构（简）

.
├── agentmem/          # 核心源码
├── benchmarks/        # 评测、消融与演示脚本 + 场景数据
├── tests/             # 单元测试
├── scripts/           # CI / 辅助脚本
├── results/           # 结果日志与生成图
├── docs/              # 说明书配图
├── docker/            # 容器构建文件
├── requirements.txt
└── README.md