AgentMem

面向长生命周期智能体的分层 KV Cache 与上下文内存管理系统。

AgentMem 使用不可变上下文 DAG 表示多轮对话和推理分支，通过引用计数与 Copy-on-Write 共享公共前缀；缓存控制器根据分支扇出、活跃租约、重计算成本和数据语义，在 GPU、CPU 与 NVMe 之间进行分层管理。大型工具输出保存在租户隔离的内容寻址存储中，Prompt 仅保留摘要和按需读取句柄。

功能

上下文 DAG、多会话、多分支、检查点和 Copy-on-Write。
模型、Tokenizer 配置和租户共同参与缓存键计算，避免不安全复用。
Agent-aware 与 LRU 两种缓存策略，以及 GPU 容量准入控制。
GPU、CPU、NVMe 三层逻辑缓存与迁移决策。
JSON、文本和二进制工具结果的压缩、去重、分页及 JSON Pointer 读取。
无第三方依赖的 HTTP 控制面、Prometheus 文本指标和 CLI。
确定性模拟后端、四组消融 Benchmark 和真实 vLLM 流式 Benchmark。
openEuler 控制面容器与 OpenAI-compatible vLLM 客户端。

flowchart LR
    A[Agent Runtime] --> B[Context DAG]
    B --> C[Agent-aware Cache Controller]
    C --> D[vLLM Adapter]
    D --> E[GPU Hot Tier]
    D --> F[CPU Warm Tier]
    D --> G[NVMe Cold Tier]
    A --> H[Tool Artifact Store]
    H --> B

快速开始

要求 Python 3.9 或更高版本。

python -m pip install -e .
agentmem --data-dir .agentmem demo --branches 3
pytest

运行四组可复现模拟对照：

agentmem benchmark --rounds 8 --branches 4 --output benchmark-results

结果写入 benchmark-results/results.json 和 benchmark-results/report.md。

启动控制面：

agentmem --data-dir /var/lib/agentmem serve --host 0.0.0.0 --port 8080
curl http://127.0.0.1:8080/healthz
curl http://127.0.0.1:8080/metrics

创建会话：

curl -X POST http://127.0.0.1:8080/sessions \
  -H 'Content-Type: application/json' \
  -d '{"model_id":"Qwen/Qwen2.5-3B-Instruct","tenant_id":"demo","system_prompt":"You are an operations agent."}'

第一阶段：Qwen 3B AWQ

Windows + NVIDIA GPU 环境可使用固定版本脚本启动数据面：

powershell -ExecutionPolicy Bypass -File scripts\start-vllm.ps1 -Variant agentmem -Replace

安装本项目并启动连接真实 vLLM 的控制面：

python -m pip install -e .
agentmem --data-dir D:\AgentMem\control-plane serve --host 127.0.0.1 --port 8080 --vllm-url http://127.0.0.1:8000 --tokenizer-model Qwen/Qwen2.5-3B-Instruct-AWQ

在另一个终端执行完整验收：

python scripts\verify_phase1.py

脚本验证 Qwen 非流式与 SSE 流式 Chat API、AgentMem 控制面、真实生成和回答回写。固定环境、权重哈希和实测指标见第一阶段实测报告。

四套真实配置

仓库提供 native、prefix、prefix-offload、agentmem 四个固定配置。模型、缓存、KV 冷层和结果默认都放在 D:\AgentMem：

.\scripts\start-vllm.ps1 -Variant prefix-offload -Replace
.\scripts\run_variant_benchmarks.ps1 -ResultsRoot D:\AgentMem\results\variants

prefix-offload 使用受限的 1GB CPU KV 层；完整 agentmem 额外将 D:\AgentMem\kv-cache 作为文件系统冷层，并启用工具结果外置和 Agent-aware 策略。配置、真实日志证据和四组结果见第二至第四阶段报告。

第五至第七阶段默认使用更适合本机的 Qwen2.5 1.5B AWQ，并执行每组预热 5 次、正式重复 3 次的公平实验。下载校验、7B 服务器限制、完整指标和原始结果见第五至第七阶段实测报告。

vLLM 集成

AgentMem 不重复实现 vLLM 已有的 CUDA KV 搬运内核。控制面负责智能体生命周期、稳定上下文、工具外置和策略元数据，实际张量缓存由 vLLM Automatic Prefix Caching 与 OffloadingConnector 管理。可通过以下代码生成启动参数：

from agentmem.backends import VLLMBackend

print(VLLMBackend.serve_command("Qwen/Qwen2.5-3B-Instruct"))

真实 Benchmark 示例：

agentmem --data-dir .real-bench real-benchmark \
  --base-url http://127.0.0.1:8000 \
  --model-id Qwen/Qwen2.5-1.5B-Instruct-AWQ \
  --layers 28 --kv-heads 2 --head-dim 128 \
  --warmups 5 --repetitions 3 --branches 2 \
  --variant agentmem \
  --output benchmark-results/agentmem-real.json

文档

当前边界

本仓库实现的是可运行的 AgentMem 控制面和策略原型。模拟 Benchmark 可在 CPU 环境完成 CI 验证；仓库中的真实实测只代表报告所列固定硬件、模型、参数和小样本负载，生产或比赛结论仍应在目标环境中重复运行 real-benchmark。

License

MIT