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

AgentMem 是一个面向长生命周期智能体推理的内存管理原型系统，基于 openEuler 24.03（WSL2）、CUDA 版 llama.cpp 和 Qwen2.5-1.5B-Instruct GGUF Q4_K_M 实现。系统面向多轮对话、工具调用与多会话暂停/恢复场景，在不改变模型、硬件、任务集和工具能力的前提下，通过上下文结构化管理、工具结果外置和会话级 KV Cache 生命周期管理，降低输入上下文开销并改善端到端推理效率。

项目贡献

1. 会话级 KV Cache 生命周期管理。 基于 llama.cpp slot API 实现会话 KV 的保存、擦除、恢复与 LRU 回收；全部状态转换和服务端返回均持久化，失败时显式退化为 Prompt 重建。
2. 结构感知的工具结果外置。 采用 SHA-256 内容寻址保存大型 JSON 工具结果，仅将任务相关摘要和引用置入上下文，并提供按路径读取接口。
3. 可归因的三模式评测。 设置 Baseline、Native Cache 与 AgentMem Optimized 三种模式，区分 llama.cpp 原生前缀缓存与本项目结构化优化的作用。
4. 可复现的真实环境验证。 固定 openEuler、GPU、模型文件、量化方式、llama.cpp 版本、服务参数及工作负载；保留 JSONL、环境哈希和 KV 事件作为审计证据。

已验证环境

项目	配置
操作系统	openEuler 24.03（WSL2）
GPU	NVIDIA GeForce GTX 1650 Ti，4 GB 显存
推理后端	llama.cpp 10107 (c0bc8591e)，CUDA 构建
模型	Qwen2.5-1.5B-Instruct GGUF Q4_K_M
模型 SHA-256	6a1a2eb6d15622bf3c96857206351ba97e1af16c30d7a74ee38970e434e9407e

核心结果

在固定 -c 4096、相同模型、GPU 和工具密集工作负载下，AgentMem Optimized 与 Baseline 均完成 3/3 任务；平均服务端 Prompt Token 从 6,164.333 降至 1,965.667（降低 68.1%），平均端到端延迟从 31,572.921 ms 降至 2,753.711 ms（降低 91.3%）。同时，系统在真实 llama.cpp 服务上完成了 KV save、erase 与 restore，恢复事件可由服务端返回审计。

固定上下文容量下，llama.cpp 会预分配 KV Buffer，因此 nvidia-smi 峰值显存不随实际输入 Token 的降低而必然变化。本项目不将该场景的相同峰值显存表述为显存节省；完整测量边界与原始证据见测试报告。

文档导航

文档	内容
技术方案说明	问题定义、设计目标、优化机制和需求覆盖范围
系统设计与实现	模块架构、数据流、核心接口和实现细节
部署与复现指南	openEuler 环境部署、服务启动、验证与 Benchmark 复现
测试报告	实验协议、真实结果、限制和证据索引
接口规范与验证记录	llama-server 接口约束、动作协议和真实接口验证
文档索引	提交材料与原始证据导航

快速复现

在 openEuler 环境中完成 llama.cpp CUDA 构建、模型准备和服务启动后：

cd /mnt/e/OSproject/OS-AI-

# 代码自检
python3 -m compileall agent memory benchmark scripts tests
python3 -m unittest -v

# 接口验证
python3 scripts/capture_llama_server_samples.py \
  --base-url http://127.0.0.1:8080 \
  --output-dir results/llama-server-integration

# 三模式评测
python3 -m benchmark.run_benchmark \
  --client http \
  --base-url http://127.0.0.1:8080 \
  --modes baseline,native-cache,optimized \
  --output-dir results/benchmark/run-new \
  --state-root runtime/benchmark/run-new

具体依赖、命令参数、结果结构和故障处置见部署与复现指南。

代码与证据目录

agent/       智能体推理循环、HTTP 客户端、Prompt 与工具
memory/      工具数据外置、KV 生命周期与 slot 适配
benchmark/   固定工作负载、指标采集与三模式运行器
scripts/     服务启动、环境记录与接口证据采集
tests/       不依赖 GPU 的回归测试
docs/        技术文档
results/     真实实验 JSONL、汇总与接口验证证据

注：ours/ 保存项目筹备阶段的内部过程记录，不构成提交材料或性能结论；评审所需内容以本 README 与 docs/ 为准。