MemLink

MemLink 是一个面向多智能体协作的低开销通信、语义状态传递与共享记忆框架。项目围绕多 Agent 协作中的三个系统层问题展开：

Agent 之间如何避免大量自然语言长文本重复传递。
上游 Agent 的中间状态如何以语义向量等非文本形式交给下游 Agent 使用。
连续任务中形成的证据、摘要和策略如何沉淀为共享记忆并被后续任务复用。

当前实现提供 FastAPI 后端、React + Vite 前端、多 Agent runtime、四种通信模式对比实验、实验指标导出和答辩可视化页面。

1. 项目结构

backend/                    FastAPI 服务、多 Agent runtime、实验执行与指标导出
frontend/                   React + Vite 可视化答辩页面
scripts/                    部署、启动和停止脚本
其他提交文档/              系统设计、技术报告、实验报告、部署与迭代文档
项目说明书.docx             按官方模板编排的完整项目说明书
MemLink.pptx                项目答辩演示文稿
演示视频.mp4                系统运行与可视化演示视频

2. 核心能力

MemLink 当前包含以下模块：

模块	说明
多 Agent runtime	Planner、Retriever、Writer、Evaluator、Coder 等角色协同运行。
结构化通信协议	使用 `ProtocolMessage`、`ProtocolAdapter` 和 `MessageBus` 统一记录消息。
语义状态传递	将 BGE embedding 生成的 semantic vector 直接放入协议消息，并以 `state_id` 锚定可审计证据。
共享记忆模块	`MemoryStore` 保存跨任务记忆，支持标签、关键词和语义相似度检索。
实验评测模块	导出 `messages.csv`、`runs.csv`、`llm_tool_metrics.csv`，并由 Coder Agent 通过受控 CodeAct 通道执行白名单分析算子，生成结构化结论与图表数据。
答辩可视化页面	展示 Agent 通信、四模式对比、单任务详情、通信载荷和连续任务趋势。

3. 四种通信模式

模式	含义
`text_only`	纯文本协作模式，作为传统自然语言传递 baseline。
`structured_text`	结构化协议模式，将动作、参数、证据和结果组织为可解析字段。
`state_ref`	语义状态模式，直接传递 semantic vector，并用 `state_id` 锚定证据。
`memory_augmented`	在语义状态传递基础上加入共享记忆检索和复用。

4. 环境要求

组件	要求
操作系统	面向 openEuler 24.03-LTS-SP3 部署与复现，同时支持本地 macOS 开发环境
Python	3.11
后端环境	conda 环境 `memlink`
后端框架	FastAPI
前端框架	React + Vite
Node.js	建议 20+
LLM 接口	OpenAI-compatible API，当前可配置 DeepSeek
Embedding	`BAAI/bge-small-zh-v1.5`

5. 一键部署

从仓库根目录执行：

chmod +x scripts/*.sh
./scripts/deploy.sh

deploy.sh 会创建或复用 conda 环境 memlink、安装后端及测试依赖、安装前端依赖并完成生产构建。

6. LLM 配置

后端使用 OpenAI-compatible API。以 DeepSeek 为例：

cd backend
cp .env.example .env

编辑 backend/.env：

DEEPSEEK_API_KEY=your_api_key
DEEPSEEK_MODEL=deepseek-chat
DEEPSEEK_BASE_URL=https://api.deepseek.com

7. 一键启动与停止

启动完整系统：

./scripts/start.sh

浏览器访问：

http://127.0.0.1:5182/

停止系统：

./scripts/stop.sh

scripts/start.sh 会在当前终端持续托管服务，可按 Ctrl+C 停止，也可在另一终端执行 ./scripts/stop.sh。脚本不会按端口结束进程；若 8012 或 5182 已被其他服务使用，启动会直接退出并保留原服务。可使用 MEMLINK_BACKEND_PORT、MEMLINK_FRONTEND_PORT 和 MEMLINK_API_BASE 调整地址。

手动启动命令与详细部署说明见 其他提交文档/部署与复现指南.md。

8. 测试与构建

后端测试建议从仓库根目录执行：

conda run -n memlink pytest backend -q

前端构建：

cd frontend
npm run build

说明：后端测试从仓库根目录运行可以避免 corpus、artifact 等相对路径差异。

9. 复现实验

前端页面提供：

运行当前任务。
一键全跑 10 个连续任务真实实验。
单任务四模式详情。
10 任务四模式对比。
通信载荷查看器。

实验产物写入：

backend/data/experiments/<experiment_id>/

关键文件包括：

canonical_inputs/
traces/
metrics/messages.csv
metrics/runs.csv
metrics/llm_tool_metrics.csv
metrics/summary_real.json
metrics/codeact_analysis.json

其中：

messages.csv 记录 Agent 间每条协议消息的字节开销。
runs.csv 记录每个任务、每种模式的通过情况、链路校验、语义状态和记忆命中。
llm_tool_metrics.csv 记录 LLM 与工具调用开销。
summary_real.json 汇总真实实验结果，codeact_analysis.json 保存 Coder Agent 的结构化分析结论。

10. 项目文档

仓库内的项目说明、PPT 和视频位于根目录，其余提交材料集中放在 其他提交文档/：

文件	用途
`其他提交文档/系统设计文档.docx`	系统总体架构、通信协议、State Exchange、共享记忆与评测设计。
`其他提交文档/技术报告.docx`	技术原理、关键实现、工程难点、创新点和实验结论。
`其他提交文档/实验报告.md`	10 个连续任务、40 次模式运行及通信、质量、链路和记忆指标。
`其他提交文档/部署与复现指南.md`	环境安装、服务启动、实验执行与产物检查方法。
`其他提交文档/迭代开发记录.md`	原生 Harness、结构化协议、语义状态、共享记忆与 CodeAct 的演进过程。
`其他提交文档/作品原创承诺书.pdf`	赛事要求的原创承诺材料。
`项目说明书.docx`	按官方模板编排的完整项目说明书。
`MemLink.pptx`	项目答辩演示文稿。
`演示视频.mp4`	系统运行与可视化演示视频。