LiteAgent-Memory

LiteAgent-Memory 是面向“多智能体协作的低开销通信、状态传递与共享记忆机制”赛题的可运行原型。项目重点不是简单编排 Agent，而是验证多 Agent 协作中的系统层机制：结构化通信协议、非文本状态引用、共享记忆复用、运行时传输编码和可复现实验评测。

目标运行环境：openEuler 24.03-LTS-SP3 x86_64，Python 3.10+。

核心功能

4 个协作 Agent：Planner、Retriever、Executor、Summarizer。
纯文本协作模式：模拟传统长自然语言上下文和完整证据在 Agent 间反复传递。
结构化协议模式：使用 AgentMessage 显式传递 action、params、result、capability、state_ref。
优化模式：结构化协议 + MessagePack 编码 + 共享内存字节通道 + state_ref + SQLite 共享记忆。
非文本状态传递：检索证据写入 StateStore，下游只传递 state://... 引用，并按需读取结构化 payload。
共享记忆：保存 memory_id、来源 Agent、创建时间、任务主题、摘要、标签、证据、策略和向量。
真实连续任务：10 轮 openEuler/Linux 场景，覆盖 systemd 故障诊断和应用迁移评估两组任务。
CodeAct 风格执行：Executor 在存在 state_ref 时通过轻量 Python 沙箱分析证据 payload。
实验输出：JSON、CSV、Markdown、HTML dashboard、SVG 图表。

快速运行

Windows PowerShell：

cd "E:\caozuoxitongdasai\研究生创新大赛\研究生创新大赛\agentlink-memory-gitlink-sync"
python -m pip install -r requirements.txt
python run_demo.py
python run_experiment.py --repeat 3 --output outputs
python -m pytest tests/ -v

openEuler：

cd ~/agentlink-memory-gitlink-sync
python3 -m venv .venv
source .venv/bin/activate
python -m pip install -r requirements.txt -i https://pypi.tuna.tsinghua.edu.cn/simple
python run_demo.py
python run_experiment.py --repeat 3 --output outputs
python -m pytest tests/ -v

一键验证：

bash scripts/verify_openeuler.sh

实验任务

examples/continuous_tasks.json 包含两组具有关联性的连续任务：

linux_diagnosis：systemd 服务启动失败、端口占用、权限错误、Redis 依赖缺失、故障报告生成。
openeuler_migration：Python 依赖检查、Go 兼容性、RPM 打包、迁移测试策略、最终迁移报告。

这两组任务用于验证结构化通信、非文本状态传递和共享记忆复用在真实 openEuler/Linux 场景中的效果。

主要输出

outputs/experiment_results.json
outputs/experiment_results.csv
outputs/metrics_summary.json
outputs/metrics_summary.csv
outputs/experiment_report.md
outputs/dashboard.html
outputs/metrics_chart.svg

评测指标

Agent 间消息次数。
字符开销与 token 估算开销。
MessagePack 相比 JSON 的字节节省率。
state_ref 传递次数、状态数据规模、避免重复传输字符数。
共享记忆命中率、准确率、召回率和误命中次数。
本地 wall-clock 原型开销。
估算协作时延：用于说明真实 LLM 场景下 token 解码、长上下文解析和 payload 传输减少带来的收益。

正式实验输出中包含以下关键字段：

token_saving_rate
char_saving_rate
estimated_latency_saving_rate
memory_hit_rate
memory_precision
memory_recall
false_memory_hit_count
state_transfer_count
state_ref_avoided_chars
msgpack_saving_rate
shared_memory_transfer_count

项目结构

agents/       四类 Agent、真实检索语料和领域标签推断
runtime/      运行时、路由、调度、能力注册
protocol/     AgentMessage、JSON/MessagePack 编解码、握手与能力发现
state/        hash embedding、StateStore、state_ref 和结构化 payload
memory/       SQLite MemoryStore、关键词/标签/语义综合检索
transport/    direct 与 shared_memory 字节通道
evaluation/   指标统计、实验运行、报告和 dashboard 生成
examples/     10 轮真实连续任务
tools/        Python 沙箱执行模块
tests/        单元测试与集成测试
docs/         设计、部署、实验、答辩文档

可选增强

默认 embedding 使用确定性 hash embedding，保证轻量和可复现。如果本地有 bge-m3 模型，可设置：

export BGE_M3_PATH=/path/to/bge-m3

程序会自动尝试加载，失败时回退到 hash embedding。