MemWeave-RT（织忆）

面向多智能体协作的低开销通信、非文本状态传递与共享记忆运行时。

MemWeave-RT 不是对工作流框架的简单包装。它用 4 个独立 Agent 进程、Unix Domain Socket、紧凑二进制协议、POSIX 共享内存和 SQLite WAL，完整实现了“规划—检索—执行—总结”的系统层协作闭环；同一运行时还保留了纯文本基线，可以一条命令完成公平的 A/B 实验。

1. 一分钟复现

环境要求：Python 3.11+，Linux/openEuler 或 macOS；项目无第三方运行依赖。

make doctor
make test
make demo
make benchmark
make dashboard

打开 http://127.0.0.1:8080 查看实验控制台。也可以执行 make verify 一次完成环境检查、测试和 10 轮对照实验。

2. 初赛提交材料

按赛事要求，提交材料已同时放在仓库根目录：

MemWeave-RT_项目说明书.docx：完整设计、实现、实验与部署说明；
MemWeave-RT_项目说明书.pdf：便于在线预览的同内容版本；
MemWeave-RT_答辩演示.pptx：基于官方 18 页模板制作的可编辑演示稿；
MemWeave-RT_演示视频.mp4：4 分 12 秒、1280×720、H.264/AAC、约 8.1 MB；
MemWeave-RT_作品原创承诺书.pdf：按官方模板完成手抄并填写日期的承诺书扫描件。

实验报告、说明书、PPT 与视频均采用 openEuler 24.03-LTS-SP3 实测结果；完整环境信息、终端记录和逐任务数据保存在 reports/。

3. 系统架构

flowchart LR
  O["Orchestrator
同任务双模式调度"] --> B["Broker
握手·能力发现·路由·计量"]
  B <-->|"MWRT 二进制帧 / 纯文本帧"| P["Planner 进程"]
  B <-->|"MWRT 二进制帧 / 纯文本帧"| R["Retriever 进程"]
  B <-->|"MWRT 二进制帧 / 纯文本帧"| E["Executor 进程"]
  B <-->|"MWRT 二进制帧 / 纯文本帧"| S["Synthesizer 进程"]
  P -->|"StateRef：192维 float32"| X["POSIX 共享内存
校验和·维度·类型·TTL"]
  X --> R
  X --> E
  E -->|"证据状态"| X
  R <--> M["SQLite WAL 共享记忆
关键词·标签·语义混合检索"]
  S --> M
  B --> T["Telemetry / Benchmark
消息·字节·状态·时延·命中率"]

关键设计：

结构化协议：消息包含 kind/action/params/result/capabilities/state_refs，以 MWRT 帧头和自研类型化二进制编码传输；Agent 接入时握手并发布能力，Broker 提供能力发现。
非文本状态：确定性多语种哈希向量器生成 192 维 float32 语义向量；只传递带校验和的 StateRef 描述符，接收方直接映射共享内存，不做“向量—文本—向量”往返。
共享记忆：统一记忆单元保存 ID、来源 Agent、UTC 时间、主题、摘要、标签、证据和向量；检索将关键词、标签与余弦相似度融合。
跨任务复用：两组连续故障诊断任务分别覆盖 CPU 调度拥塞和存储写放大，第二个关联任务优先复用第一个任务沉淀的证据与策略。
CodeAct 沙箱：执行 Agent 可在 AST 白名单、子进程隔离、超时和资源上限下运行受控 Python 表达式。

详细设计见 docs/DESIGN.md，协议见 docs/PROTOCOL.md。

4. 当前可复现实验结果

reports/benchmark.json 是 2026-07-24 在 openEuler 24.03-LTS-SP3（aarch64、Python 3.11.6）完成的实测结果：每种模式 10 轮、2 组任务、每组 2 个连续任务，共 40 个任务/模式。reports/benchmark-openeuler.json/csv 保留同次原始输出，reports/openeuler-validation.log 保留环境检查与 24 项测试记录。

指标	纯文本模式	结构化模式	改善
成功率	100%	100%	持平
消息数	320	320	控制变量
Payload 字节	980,578	437,074	55.43%
估算 token 等价量	245,158	109,290	55.42%
平均任务时延	14.782 ms	5.356 ms	63.77%
共享记忆命中率	95%	95%	持平
命中后复用正确率	100%	100%	持平
非文本状态传递	0	200 次 / 153,600 B	直接交换

估算 token 等价量统一按 UTF-8 payload 字节数除以 4 向上取整，仅作为模式间同口径通信量代理，不声称等同于具体模型 tokenizer。完整口径和限制见 docs/EXPERIMENT.md。

5. 赛题验收对照

官方要求	实现位置	可验证证据
不少于 3 个 Agent、至少 3 类角色	`memweave/agents.py`、`runtime.py`	4 个独立进程；集成测试
动作、输入、结果、能力；握手/发现	`protocol.py`、`transport.py`	`discover_capabilities()`；协议测试
纯文本与结构化双模式	`protocol.py`、`benchmark.py`	同任务同轮次 A/B 报告
非文本状态直接交换	`state.py`	共享内存 `StateRef`；校验测试
统一共享记忆元数据	`memory.py`	SQLite 表结构；存取测试
关键词/标签/语义检索	`memory.py`	混合检索排序测试
两组关联连续任务	`tasks.py`	CPU / Storage 各 2 个任务
指标与不少于 10 轮	`telemetry.py`、`benchmark.py`	40 任务/模式 JSON 与 CSV
运行时/协议/状态/记忆/评测	`memweave/`	五类模块均可独立定位
CodeAct 轻量沙箱（加分项）	`sandbox.py`	策略拒绝、超时、正确执行测试

6. 目录

memweave/                 运行时、协议、状态、记忆、评测、控制台
tests/                    单元与多进程集成测试
scripts/                  本地及 openEuler 验证脚本
docs/                     设计、协议、部署、实验与匿名自查
reports/benchmark.*       可复现实验原始结果
MemWeave-RT_*             根目录提交材料
deliverables/assets/      说明书使用的架构图与实验图

7. 匿名与安全

仓库、文档和控制台不包含学校、教师或成员姓名；提交前请执行 python3 scripts/anonymity_check.py。系统仅使用本地 IPC，不调用云端模型或服务；Web 控制台默认只监听 127.0.0.1 且只读。

8. 开源许可

Apache License 2.0，见 LICENSE。