CoMem

面向多智能体协作的低开销通信 · 非文本状态传递 · 共享记忆机制

主流多 Agent 系统以自然语言 / JSON 文本作为智能体间的通信媒介，带来三个结构性问题： 通信开销高（token 随协作轮次线性膨胀）、状态反复编解码（向量↔文本来回转换）、 知识无法沉淀（相似任务从头重算）。CoMem 用一套可运行、可复现、可量化的原型验证三条改进路径， 并通过「结构化协作（STRUCT）vs 纯文本协作（TEXT）」的对照实验加以量化。

核心结果（11 任务链实测，真实 bge-m3）

指标	TEXT 纯文本	STRUCT 结构化	改进
上线 token	9439	4017	节省 57.4%
工具 / LLM 调用次数	22	11	2.0× 加速
跨任务记忆命中率	0%	90.9%	——

三个头条指标均为确定性，多次运行完全一致。

架构

comem/
├─ runtime/     ① 多 Agent 运行时      角色化智能体 + 回合调度
├─ protocol/    ② 协议解析与调度        结构化通信 + TEXT/STRUCT 双模式 + 握手/能力发现
├─ state/       ③ 状态交换             真实 embedding + 非文本状态直接传递
├─ memory/      ④ 共享记忆存储与检索    全元数据、三路检索、跨任务复用
├─ eval/        ⑤ 评测                token/耗时/命中率统计 + 双模式实验编排
├─ tasks/       关联连续任务链 + Executor 工具
└─ llm.py       可选 LLM 接入（不设 key 则跑离线确定性模式）

快速开始

pip install -r requirements.txt

python cli.py info            # 查看 embedding / tokenizer 后端
python cli.py experiment      # 双模式对比，落盘 reports/report.md + report.json
python cli.py demo --mode struct   # 逐步打印一次协作过程
python run.py                 # Web 看板 http://127.0.0.1:8000
python -m pytest -q           # 核心机制测试

真实 bge-m3 模型体积较大，不随仓库提交。将模型放到 ./models/bge-m3/， 或用环境变量 COMEM_EMBED_MODEL 指定路径；未提供时自动回退哈希词袋后端（real_model=false），服务仍可运行。

Docker 部署（openEuler 24.03）

详见 DEPLOY.md。

docker compose up --build                                # 看板
docker compose run --rm comem python3 cli.py experiment  # 出报告

设计文档

完整设计说明见 设计文档.md。