AgentMem-KV

AgentMem-KV 是一个构建于 vLLM 之上的智能体长上下文内存管理系统。它面向多轮对话、工具调用和长期任务中不断膨胀的上下文：当工具返回大量 JSON、表格、检索结果或历史记录时，系统避免将这些内容在后续请求中反复完整写入 prompt，从而减少模型 prefill、KV Cache 压力和端到端延迟。

系统位于 Agent 与 vLLM 之间：完整工具结果被无损保存到 SQLite；模型只接收稳定引用、结构摘要和与问题相关的证据，并可通过引用按需检索完整内容。项目在 LoCoMo、LongMemEval-V2 和 BFCL V4 上评估任务质量、实际 prefill、峰值 active KV 和延迟，并提供可复现实验结果与可视化图表。

Agent / tools → AgentMem-KV → vLLM
                    ├── 完整工具结果：SQLite 外置保存
                    └── 模型上下文：摘要 + 相关证据 + 稳定引用

提交文档

项目说明书：项目背景、技术路线、功能模块、实验测试、实现难点与总结。

结果概览

O3 在长记忆工作负载中将每次请求的 prompt 从约 25k–29k tokens 缩减到约 1.3k–1.4k tokens，6 个模型—数据集组合的 uncached prefill 均减少约 95%，峰值 active KV 减少 79.5%–94.5%，P95 延迟减少 37.7%–81.8%。

在原生多轮工具调用 BFCL V4 中，三个模型的 uncached prefill 减少 24.8%–50.3%；Qwen3-4B 的峰值 active KV 降低 47.66%，Qwen3-30B-A3B 的 P95 请求延迟降低 45.1%。任务质量使用各基准的官方指标独立报告，详细结果见后文。

核心设计

系统由三个协同层组成：

层级	作用	定位
O1 · Prompt Canonicalization	对 system prompt、工具 schema 和文本进行确定性序列化，稳定可复用前缀	稳定输入能力
O2 · SegmentDAG + PromptBuilder	以内容哈希组织上下文片段，记录会话关系、引用和 provenance，并生成 prefix-first prompt	结构化上下文管理能力
O3 · Tool-result Externalization	将完整的长文本工具结果无损写入 SQLite，prompt 只保留 schema、摘要、query-relevant evidence 和稳定引用；执行工具前解析引用	核心资源优化

O3 改变后续请求的模型输入及其实际 prefill。原始内容仍保存在外部存储中，后续工具参数中的引用可还原为原始值。BFCL 集成保留官方交互循环、工具实现和评分器，仅调整工具结果写回 prompt 的处理方式，因此 baseline/O3 实验的对照变量明确。

项目通过 vLLM 指标与只读引擎 block trace 记录实际 prompt、uncached prefill、prefix cache、峰值 active KV 和请求延迟。O1/O2 为 O3 提供稳定输入与结构化上下文能力，资源优化效果以 vLLM 观测到的实际变化为准。

评测方案

评测覆盖以下三个模型：

Qwen/Qwen3-4B
Qwen/Qwen3.6-27B
Qwen/Qwen3-30B-A3B-Instruct-2507

LoCoMo

实验使用的 LoCoMo 数据版本为 snap-research/locomo@3eb6f2c，使用全部 1,542 个 QA 样本。评测将每个样本的长对话记忆物化为 locomo_memory_lookup 的工具结果，在保持原问题、标准答案和 LoCoMo F1 评分不变的前提下，对比完整上下文与 O3 检索式外置。评测矩阵为三模型 × baseline/O3 × 3 次独立冷启动。

LongMemEval-V2

实验使用的 LongMemEval-V2 数据版本为 xiaowu0162/longmemeval-v2@f152293，保留全部 451 个问题。为统一三种模型的输入并适配其中最小的上下文窗口，每题均使用 small haystack 投影（最多 12 条 trajectory、每条 6 个 state、每个 state 1,000 字符）。该设置用于统一上下文构造，不涉及问题抽样。评测矩阵同样为三模型 × baseline/O3 × 3 次独立冷启动。长记忆被物化为 longmemeval_memory_lookup 的工具结果；系统指标覆盖全部 451 题，其中 295 题使用官方确定性 evaluator 计算 accuracy，另外 156 题需要外部 LLM judge，不计入上述准确率统计。

BFCL V4

BFCL 评测使用的代码版本为 ShishirPatil/gorilla@6ea5797。每个配置包含 1,265 个计分任务和 111 个 Memory 前置轨迹：

类别	样本数
`multi_turn_base`	200
`multi_turn_long_context`	200
`multi_turn_miss_func`	200
`multi_turn_miss_param`	200
`memory_kv`	155 + 37 prereq
`memory_vector`	155 + 37 prereq
`memory_rec_sum`	155 + 37 prereq

三模型 × baseline/O3 共获得 7,590 条评测结果。评测使用 BFCL 官方本地执行器和确定性评分，不调用外部 LLM judge。BFCL 每个配置运行一次。

LoCoMo / LongMemEval-V2 评测结果

O3 在这两个数据集上使用 Retrieval_Hybrid_Rerank_Direct_K4：session-aware chunks、BM25+dense 候选、cross-encoder rerank 和 top-4 direct evidence。表中质量分别采用 LoCoMo F1 和 LongMemEval-V2 的确定性评分；资源指标列均为相对 baseline 的下降比例。

模型	数据集	质量 baseline → O3	Uncached prefill reduction	P95 reduction	Peak active KV reduction
Qwen3-4B	LoCoMo 1,542	0.213 → 0.460	95.07%	37.70%	94.47%
Qwen3-4B	LongMemEval-V2 451	7.80% → 13.11%	95.50%	61.40%	93.23%
Qwen3-30B-A3B-Instruct-2507	LoCoMo 1,542	0.266 → 0.492	95.09%	54.79%	94.55%
Qwen3-30B-A3B-Instruct-2507	LongMemEval-V2 451	11.53% → 11.30%	95.51%	59.68%	93.23%
Qwen3.6-27B	LoCoMo 1,542	0.591 → 0.534	94.73%	81.77%	79.55%
Qwen3.6-27B	LongMemEval-V2 451	10.06% → 9.49%	95.28%	45.92%	80.43%

Qwen3-4B 在两个数据集、Qwen3-30B-A3B 在 LoCoMo 上同时获得质量与资源收益；其余组合体现明确的质量—资源权衡。该组实验反映的是 O3“外置 + 检索 + rerank”的联合效果，其中质量提升来自相关证据聚焦，不能单独归因于上下文缩短。

BFCL 评测结果

表中延迟基于 BFCL 全部计分任务产生的模型请求统计；Uncached prefill 和 Peak active KV 来自同次运行的 vLLM 指标与引擎 block trace。正数 reduction 表示资源下降。Multi-Turn/Memory 是此次评测所覆盖类别的官方宏平均，不使用未运行类别补零后的 BFCL 全榜 Overall 字段。

模型	Multi-Turn baseline → O3	Memory baseline → O3	平均请求延迟	P95 请求延迟	Uncached prefill reduction	Peak active KV reduction
Qwen3-4B	32.38% → 32.50%	23.44% → 21.08%	6.91s → 6.78s	18.21s → 17.82s	35.32%	47.66%
Qwen3-30B-A3B-Instruct-2507	41.75% → 39.12%	16.13% → 14.19%	2.98s → 2.09s	10.54s → 5.78s	50.31%	0.00%
Qwen3.6-27B	63.12% → 59.38%	59.35% → 53.98%	19.39s → 18.52s	72.44s → 72.44s	24.83%	0.00%

结果表明，O3 减少了实际 prefill，Qwen3-4B 的峰值活跃 KV block 同时降低 47.66%。BFCL 的准确率变化量化了真实多轮工具调用中的质量代价，为不同模型选择外置阈值、证据数量和检索策略提供依据。

LoCoMo/LongMemEval-V2 和 BFCL 的机器可读结果位于 results/release。每组结果均提供统一的 summary.csv 和 summary.json，可用于生成图表；BFCL 还提供官方 CSV、run manifest、资源指标和全部原始结果的无损压缩包，由 SHA256SUMS 校验。

完整图表套件位于 docs/figures，包含系统机制、质量、prefill、KV、延迟长尾、逐任务结果和 BFCL 子类别等 19 张图；每张图同时提供可缩放的 SVG、印刷用 PDF 和 300 DPI PNG。重新生成全部图：

scripts/plot_release_results.sh

安装

项目使用 uv 管理 Python 依赖和虚拟环境，vLLM 版本为 0.19.1，BFCL 使用上述 Git commit 对应的版本：

uv sync --extra dev --extra analysis --extra serve --extra bfcl
cp configs/local.example.yaml configs/local.yaml

编辑 configs/local.yaml，填写模型、检索器和数据集路径。模型、原始数据集和运行时缓存均不应放进源码目录。

复现实验

LoCoMo + LongMemEval-V2

先生成标准化实验输入，再运行三组完整评测矩阵：

bash scripts/prepare_o3_datasets.sh
bash scripts/run_o3_full_matrix.sh --cuda-visible-devices 1

每个矩阵内部随机化 baseline/O3 顺序，并在每次运行前冷启动 vLLM。可通过 --run-name <exact-name> --resume 恢复指定配置的执行。完成后生成统一结果表：

.venv/bin/python -m metrics.o3_result_exporter results/o3_full_matrix \
  --output-json results/release/o3_full_matrix/summary.json \
  --output-csv results/release/o3_full_matrix/summary.csv

BFCL

先检查依赖版本、七类样本数以及本地向量 Memory 后端：

.venv/bin/python -m benchmarks.agentmembench.bfcl_preflight \
  --embedding-model "$(.venv/bin/python -c \
  'from benchmarks.agentmembench.config import load_local_config; print(load_local_config()["models"]["minilm_l6_v2"])')"

列出六组实验命令，或按模型成对启动 tmux 任务：

.venv/bin/python -m benchmarks.agentmembench.run_bfcl_matrix \
  --matrix configs/benchmarks/bfcl_v4_official_full.yaml --commands

.venv/bin/python -m benchmarks.agentmembench.run_bfcl_matrix \
  --matrix configs/benchmarks/bfcl_v4_official_full.yaml \
  --job qwen3-4b-baseline --job qwen3-4b-agentmem --launch

.venv/bin/python -m benchmarks.agentmembench.run_bfcl_matrix \
  --matrix configs/benchmarks/bfcl_v4_official_full.yaml --status

配置中的 GPU 编号和端口可根据运行环境调整；每个被测配置仅使用一张 GPU。同一 GPU 上不同模型的实验需要分批运行。完成后验证并生成统一结果表：

.venv/bin/python -m metrics.bfcl_result_analyzer results/bfcl_v4_official \
  --output-json results/release/bfcl_v4_official/summary.json \
  --output-csv results/release/bfcl_v4_official/summary.csv \
  --output-md results/release/bfcl_v4_official/summary.md

agent_runner/              Agent 运行时与多轮工具调用适配
backend/                   vLLM OpenAI-compatible 客户端
memory_manager/            O1/O2/O3 核心实现
agentmem_engine/           vLLM 0.19.1 的只读 KV/调度观测
benchmarks/agentmembench/  数据适配、BFCL 协议与实验运行器
configs/                   本地路径模板、对照组和评测矩阵
metrics/                   结果验证、资源采集与统一汇总
results/release/           机器可读且可校验的评测结果
tests/                     单元与协议回归测试
tmp/                       临时运行状态（不纳入版本控制）

验证

uv lock --check
.venv/bin/python -m pytest
.venv/bin/python -m compileall agent_runner agentmem_engine backend benchmarks memory_manager metrics tools

项目背景、技术路线、实验测试与实现边界详见 docs/项目说明书.md。