LiteAgent-Memory

LiteAgent-Memory：一种面向多智能体协作的低开销通信、状态传递与共享记忆机制

第三届中国研究生操作系统开源创新大赛暨开放原子大赛操作系统专项赛
应用创新赛道 · 第 10 题

项目概览

LiteAgent-Memory 是一套可运行、可测量、可复现的多智能体协作运行时。它不把多 Agent 系统简化为提示词串联，而是从通信、状态、记忆、执行隔离和系统取证五个层面解决协作开销问题：

• 以 SCP v2.0 结构化协议替代 Agent 间冗长的自然语言透传；
• 以 StatePacket 保存语义向量等非文本状态，消息只传递 state_ref；
• 以 MemoryCell 沉淀任务摘要、证据、策略和经验，支持跨任务检索复用；
• 以 五进程 Agent + AF_UNIX RPC运行真实协作链路；
• 以 Qdrant、加固 CodeAct 容器和 eBPF构建可审计的增强验证链路；
• 以 text、structured、memory 三种模式完成严格控制变量实验。

八模型实验结果：35 个完整三模式组、2,013 项任务记录。沿用旧版通信口径，合并后 structured 和 memory 相比 text 的 Agent 间通信 Token 分别节省 56.61% 和 **55.60%**。该口径排除检索证据全文。

总体系统架构 PDF 原图

主要成果

Web 与 Windows 控制台

控制台直接读取 logs/runs/*，不依赖手工录入结果，提供：

• 总览驾驶舱；
• 五 Agent 拓扑与真实 Worker 证据；
• SCP 协议消息流；
• StatePacket 与 AF_UNIX RPC 统计；
• MemoryCell 写入、命中和复用记录；
• Text 原始基线、Structured/Memory Agent 通信 Token 对比；
• Qdrant、容器沙箱、eBPF 与 openEuler 环境证据。

Web 与 Windows 客户端提供对应的观察功能。模型通信节省按完整组汇总，其余运行指标与明细对应所选单条记录；八模型总体数据见主要成果，五模型重复实验明细见下文。

连接 openEuler 与读取记录

总览驾驶舱

展示当前模型、任务轮数、运行能力、Agent 间通信 Token 节省和 LLM 调用等指标。图中 DeepSeek 完整组汇总：Structured 节省 417,854（62.46%），Memory 节省 406,307（60.74%）。

Agent 拓扑与能力发现

SCP 协议消息流

三模式实验对比

连续运行任务对比

共享记忆与任务实例

CodeAct 容器执行

eBPF 内核取证

测试集与具体任务

为什么需要 LiteAgent-Memory

传统多 Agent 框架通常使用自然语言长文本在角色之间传递计划、证据、执行结果和历史上下文。这会带来四类系统问题：

1. 通信重复：任务背景、历史消息和证据全文在多个 Agent 之间反复传递。
2. 状态文本化：语义向量等中间状态被迫转写为文本，再由下游重新解析。
3. 经验易失：任务结束后，证据、策略和结论难以成为后续任务可检索的共享资产。
4. 缺少公平评测：协议、状态和记忆机制经常与 Agent、任务或模型同时变化，难以判断收益来自哪里。

LiteAgent-Memory 将这些问题视为运行时问题，并采用统一标识追踪完整协作链：

trace_id  -> 一轮任务的完整协作链
msg_id    -> 一条 Agent 消息
state_id  -> 一个非文本 StatePacket
memory_id -> 一条可检索 MemoryCell

五类 Agent 协作流程

系统实现五类职责明确的 LLM Agent：

三种模式：相同 Agent，只切换运行时机制

三种模式共享相同任务、Agent 顺序、模型后端和运行环境，只改变通信、状态与记忆机制：

这种设计使收益归因保持清晰：structured 相对 text 的变化来自协议与状态机制；memory 相对 structured 的变化来自共享记忆机制。

核心机制

1. SCP v2.0：结构化协作协议

SCP 将弱约束的自然语言交互收敛为可解析、可追踪、可扩展的消息载荷。核心字段包括：

{
  "protocol_version": "scp/2.0",
  "trace_id": "run_structured_..._A1",
  "from": "planner",
  "to": "retriever",
  "action": "retrieve",
  "params": {
    "query": "分析传统多 Agent 通信开销问题",
    "top_k": 5
  },
  "capability_required": [
    "semantic_search",
    "memory_lookup",
    "llm_rerank"
  ],
  "state_ref": "state_2f1cbd4228adf5fe0f",
  "memory_refs": []
}

2. StatePacket：非文本状态传递

StatePacket 用统一元数据描述二进制中间状态：

state_id · producer · state_type · dtype · shape
storage_path · offset_bytes · nbytes
tags · semantic_hint

3. MemoryCell：跨任务共享记忆

Summarizer 在任务结束后将可复用信息保存为 MemoryCell：

memory_id · source_agent · task_topic · summary
evidence · tags · embedding_ref · reuse_count
memory_level · quality_score · last_accessed_at

本轮关联问答将召回的知识原文与历史记忆来源片段放入共享上下文池，使用相同特征表示和冻结学习头统一选择。候选与空候选共同参与判别，选中的来源片段进入 Executor / Critic 上下文，并记录实际使用的记忆引用。

4. 特征提取与向量后端

• TransformerEmbeddingVectorizer：默认语义方案，使用 paraphrase-multilingual-MiniLM-L12-v2，在 CPU 上完成掩码均值池化和 L2 归一化。
• HashEmbeddingVectorizer：无网络、无深度学习依赖的确定性兜底方案；失败原因记录在结果 JSON 的 vectorizer.fallback_reason 中。

本轮中文问答采用 semantic_joint_learned（冻结 BGE-small-zh-v1.5 与联合学习特征头，4,608 维）；系统设计与连续运行采用 signed_hash_embedding（384 维）。对比在相同任务集和向量后端的三模式组内进行，不把不同任务的向量化条件当作完全相同。

系统级增强与强校验

增强模式采用严格验收链：

1. 五个 Agent 在五个独立 PID 内执行；
2. Coordinator 通过 AF_UNIX 分帧 JSON RPC 调度；
3. StatePacket 写入 POSIX 共享内存；
4. MemoryCell 通过 Qdrant 检索与持久化；
5. CodeAct 在加固容器内执行；
6. bpftrace 采集 Socket、共享内存和容器执行证据；
7. 在线模型 Token 必须来自服务端 api_usage。

CodeAct 沙箱约束

容器化 CodeAct 后端采用以下隔离策略：

• 禁止网络；
• 独立 IPC namespace；
• 只读根文件系统；
• 丢弃全部 Linux capabilities；
• 启用 no-new-privileges；
• 非 root 用户运行；
• 限制 CPU、内存和 PID 数量；
• 执行结果交由 Critic 二次复核。

五模型重复实验明细

实验设置

• 系统：openEuler 24.03 LTS-SP3；
• 内核：6.6.0-132.0.0.111.oe2403sp3.x86_64；
• 模型：Qwen3.8-Flash、DeepSeek-V4.1-Flash、Kimi-K2.6、GLM-5.2、Gemini-3.8-Flash-Control；
• 中文问答：每模式每次 30 题；系统设计：每模式每次 10 题；连续运行：每模式每次 17 轮；
• 一组必须同时具有成功且参数一致的 Text、Structured、Memory 三种模式；
• 已纳入 32 个完整组、96 条运行记录，合计 1,863 项任务、8,055 次有回执的 LLM 调用。

实验按同模型、同参数、同批次成组配对，模型名称采用接口返回标识。原始运行记录保留在服务器。

Agent 间通信 Token

沿用 protocol_no_evidence_body_v1：从 Agent 消息载荷中排除检索证据全文，保留标题、标签和其他协作消息，再做确定性 Token 估算。下表按完整组求和后计算节省比例，不取百分比的简单平均。

Structured 共节省 1,428,415 Token；Memory 共节省 1,402,496 Token。Memory 统计包含共享记忆相关协作消息。

状态、记忆与稳定性

• 96 条已选记录均保留五 Worker、Socket RPC 和 Qdrant 运行证据；
• Structured/Memory 共 64 条记录有 POSIX shm 证据，Text 不启用此机制；
• 共 1,242 次状态传递、16,100,352 字节、0 次读取校验失败；
• 共保存 621 条 MemoryCell，记忆与消息可在对应组原始 JSON 中查看；
• 系统设计与连续运行合计 72 次 CodeAct 调用、72 次成功；CodeAct 在这两类任务中触发；
• 17 条记录关联主机级 eBPF 轨迹。

实验记录按模型和任务组发布在 tests/README.md，源运行记录保留在服务器及本地备份。

指标口径

公开对比页面以 Agent 间通信 Token 为主指标；API usage 保留在结果表中。

技术路线

运行说明

环境要求

• openEuler 24.03 LTS-SP3；
• Python 3.10+，推荐 3.11+；
• Podman（推荐）或 Docker；
• 增强模式额外需要 Qdrant、bpftrace、bpftool、内核 BTF/tracefs；
• 完整 eBPF 取证需要 root 权限。

1. 获取项目

git clone https://www.gitlink.org.cn/qq1448158879/yzmxdzntxzddkxtxztcdygxjyjz.git
cd yzmxdzntxzddkxtxztcdygxjyjz/src

2. 准备配置

cp configs/runtime.env.example configs/runtime.env

真实 API 凭据只写入被 Git 忽略的 configs/runtime.env：

LLM_BASE_URL="https://your-openai-compatible-endpoint/v1"
LLM_API_KEY="sk-..."
LLM_MODEL="your-model"
LLM_TIMEOUT=300

不要把 API Key 写入命令历史、README、日志或提交记录。

3. 安装并自检

bash scripts/install_openeuler.sh
source .venv/bin/activate
python -m liteagent_memory doctor

安装 CPU Transformer 语义向量依赖：

INSTALL_SEMANTIC=1 bash scripts/install_openeuler.sh

4. 运行离线可复现实验

离线 provider 不需要 API Key，默认执行 text structured memory 三模式和 5 次重复：

bash scripts/run_all_benchmarks.sh

5. 运行真实模型实验

bash scripts/run_full_live_api.sh

脚本会先执行 provider preflight，检查服务连接、鉴权和返回结果，通过后开始实验。

6. 运行严格增强实验

bash scripts/run_enhanced_openeuler.sh

该入口会构建 CodeAct 沙箱、启动 Qdrant、运行五 Agent 进程、采集 eBPF 证据并执行强校验。

7. 启动 Web 取证控制台

.venv/bin/python -m liteagent_memory.web_server \
  --host 0.0.0.0 \
  --port 8501

浏览器打开：

http://<openEuler-host>:8501

也可以安装仓库内的 systemd 服务：

cp deploy/liteagent-web.service /etc/systemd/system/
systemctl daemon-reload
systemctl enable --now liteagent-web.service

8. 录制一次完整实验

完整 3 次重复：

bash scripts/run_complete_experiment_for_video.sh gemini-3.1-flash-lite

较短的单次重复录制：

bash scripts/run_complete_experiment_for_video.sh gemini-3.1-flash-lite 1

该脚本要求 root、可用的 liteagent-web.service 和已配置的真实模型 API。详细说明见 src/docs/VIDEO_RECORDING_GUIDE.md。

已经完成的演示视频：

• 决赛演示视频：客户端操作与真实实验，4 分 54 秒

决赛版展示读取服务器记录、任务与运行证据、模型选择和一次真实实验；本次现场实验为 10 个系统设计任务 × 3 种模式 × 1 次重复，共 30 项。模型等待片段加速，保留实际操作与 Token 节省对比，采用新版汇报解说、云希自然男声与同步字幕。

已知限制

完整系统增强实验依赖 Linux/openEuler 环境；Windows 客户端用于连接服务器、查看记录和启动实验。

输出与证据

每次运行创建独立目录，不覆盖历史数据：

logs/runs/<experiment>/
├── run_metadata.json
├── env.txt
├── benchmark.log 或 full_live_api.log
├── results/ 或 results_live/
│   ├── text_repeat*.json
│   ├── structured_repeat*.json
│   ├── memory_repeat*.json
│   ├── benchmark_summary.csv
│   └── benchmark_summary.json
├── reports/ 或 reports_live/
│   └── comparison.md
└── runtime/ 或 runtime_live/

增强运行额外生成：

enhanced_verification.json
ebpf/summary.json
ebpf/trace.log
platform/qdrant_service.json
platform/codeact_sandbox_image.json
platform/codeact_sandbox_smoke.log

其中 enhanced_verification.json 是逐项 PASS/FAIL 的机读结论；ebpf/trace.log、服务元数据和镜像元数据提供可追溯的底层证据。

仓库结构

.
├── README.md
├── src/                          # 项目源码与构建配置
│   ├── assets/                    # 首页 Logo、架构图与实际运行截图
│   ├── configs/                   # 运行配置、知识库、10/15 轮任务集
│   ├── deploy/                    # systemd Web 服务
│   ├── docs/                      # openEuler 验证与录制指南
│   ├── liteagent_memory/
│   │   ├── agents.py              # 五类 Agent
│   │   ├── agent_process.py       # 五进程 Agent 与 AF_UNIX RPC
│   │   ├── protocol.py            # SCP v2.0 与能力发现
│   │   ├── state_store.py         # mmap / POSIX StatePacket
│   │   ├── memory_store.py        # SQLite / Qdrant MemoryCell
│   │   ├── vectorizer.py          # Transformer / Signed Hash
│   │   ├── sandbox.py             # CodeAct / 容器沙箱
│   │   ├── runtime.py             # 主运行时与指标汇总
│   │   ├── report.py              # CSV / JSON / Markdown 报告
│   │   └── web_server.py          # 原生 Web API 与静态服务
│   ├── scripts/                   # 安装、实验、增强验收、取证与打包
│   ├── tests/                     # 冒烟、协议、传输、沙箱与增强测试
│   ├── web_demo/                  # 原生 Web 控制台
│   ├── Dockerfile
│   ├── Dockerfile.codeact
│   └── pyproject.toml
├── tests/                        # 实验记录
├── demo/                         # README、最新 ZIP、一个 EXE
├── 作品原创承诺书.pdf
├── docs/                         # 项目说明书、创新说明、成员贡献与工具使用说明
└── presentation/                 # 决赛现场演示 PPT 与决赛演示视频

docs/ 已提交项目说明书.pdf、项目创新说明.pdf、成员分工及主要贡献说明.pdf和人工智能及第三方工具使用说明.pdf；presentation/ 已提交决赛现场演示PPT.pptx和决赛演示视频.mp4。首页海报、图片及海报 PDF 原文件位于 src/assets/；根目录不再提交旧视频、Word、PPT 或重复 PDF。源码单元测试保留在 src/tests/，不占用根目录 tests/ 的实验材料位置。

构建与测试

源码安装入口为 src/pyproject.toml，推荐 Python 3.11+；Windows 程序构建方法见 demo/README.md。完整系统实验需原生 Linux/openEuler、Qdrant、Podman、可用内核 BTF 和 eBPF 权限；读取已保存的服务器结果无需模型 API，但仍需可用 SSH 账号和网络。

从仓库根目录执行无付费调用的测试：

python -m pip install -e './src[test]'
python src/scripts/run_validation.py

实验记录格式和统计方法见 tests/README.md。客户端回归可在安装 src/desktop/requirements.txt 后执行 python src/scripts/run_validation.py --desktop。

赛题要求对应

开源许可

项目原创代码采用 Apache-2.0，完整条款见 LICENSE，Python 包包含相同许可证正文。第三方模型、数据和依赖适用各自许可。

进一步阅读

• src/README.md：源码目录运行说明；
• src/docs/OPENEULER_ENHANCED_VALIDATION.md：openEuler 增强链路验证；
• src/docs/VIDEO_RECORDING_GUIDE.md：完整实验录制指南；
• src/configs/runtime.env.example：全部运行参数；
• src/configs/tasks_10_rounds.json：早期 10 轮任务配置；
• src/configs/tasks_15_rounds.json：早期 15 轮任务配置；
• tests/README.md：实验记录。
• 项目说明书：八模型实验设置与完整结果。

协忆智枢 · LiteAgent-Memory
让多 Agent 协作从“长文本互传”走向“协议、状态、记忆与证据驱动”。