OpenMemory

项目简介

OpenMemory 是面向多智能体（Multi-Agent）长程协作的系统层运行时原型系统，作为操作系统开源创新大赛技术成果开源发布。

在传统多智能体协作框架中，角色间常以自然语言长文本或松散 JSON 交换所有上下文，带来两方面问题：一是大量模型 Token 被消耗在反复传递不变背景与冗余中间信息上；二是下游角色难以直接使用前置分析结果，需要反复解析实体与状态。

在已有技术体系中，LangGraph 提供了状态图检查点与节点缓存，AutoGen 支持对话缓存，Ray 支持基于 ObjectRef 的不可变对象引用。OpenMemory 进一步将类型化动作分发、本地应用状态直接消费与基于依赖校验的计算复用统一接入同一运行时，在两组连续协作任务基准中完成系统化验证与因果评估。

应用场景

系统围绕真实研发运维中两组具有严密因果依赖关系的典型十轮长程协作场景构建评测基准：

源码故障影响分析（Codebase Incident & Repair）：输入真实 Python 源码快照与变更根节点（roots）。检索角色构建模块依赖图并持久化，下游合成角色直接基于当前 roots 进行图拓扑遍历，筛选受影响模块集合并由执行角色运行回归测试；
日志与遥测诊断（Log & Telemetry Diagnosis）：输入微服务集群性能指标与遥测事件流。检索角色提取特征并生成对齐的 float32 异常得分矩阵，下游角色按指定服务名与阈值进行本地高效过滤，合成精确的异常诊断报告。

两组任务均完整涵盖冷启动计算、参数变更下的派生状态复用、跨轮依赖失效判定与按需精准重算，为系统评估提供了确定性、可检验的基准场景。

主要功能

OpenMemory 提供以下相互支撑的核心系统层技术能力，前三项对应本项目的三项核心机制：

结构化双平面协作（Structured Dual-Plane Collaboration, C1）：建立强类型化通信协议与不可变引用机制（ProtocolRef），将模型可见的控制指令（意图、参数、句柄）与底层数据载荷解耦。在同等任务完成质量下，代码分析场景的 API-total-token 节省率配对中位数达 **79.83%**（累计总量节省 **79.92%**），日志诊断场景达 **80.16%**（累计总量节省 **79.78%**）；
机器原生状态就地消费（Machine-Native State Consumption, C2）：将中间派生计算结果表示为结构化图描述符或 float32 二进制向量，支持下游消费者直接在本地完成拓扑遍历或余弦过滤等运算；两组任务的状态开启/关闭（ON/OFF）因果验证均为 60/60；
基于依赖校验的计算复用（Dependency-Validated Computation Reuse, C3）：构建感知版本演进与输入有效性的共享记忆存储，在上游源码或数据依赖未发生实质变动时复用历史派生计算产物，在依赖变更或校验失败时拒绝旧状态并重算；两组任务各自六条 B3 序列累计 42 次有效复用、12 次必要重算、0 次错误复用；
多执行拓扑与 Linux 状态通道：任务图（TaskGraph）支持串行、扇出/汇聚（Fan-out/Fan-in）、独立子进程与远程端点多种拓扑；在 Linux 目标平台上支持基于文件后备内存映射（mmap）与 Unix 域套接字（UDS）的跨进程传输通道；
四层分层记账与脱敏审计：系统分层记录模型服务商（Provider）、控制序列化（Control）、物理传输（Transport）与逻辑存储（Storage）四层收据，指标计算全部来自真实底层捕获数据，杜绝推算估算。

系统环境与依赖要求

1. 目标运行环境

权威交付平台：openEuler 24.03-LTS-SP3（CPU 架构：x86_64）
开发与日常测试平台：macOS（Apple Silicon / Intel）、Ubuntu 22.04+、Debian 12+
容器与虚拟化引擎：Docker 24.0+，Docker Compose v2.20+

2. 软件依赖要求

核心编程语言：Python 3.11（严格指定，通过 Conda 或系统 Python 提供）
Python 核心依赖：无。基础安装不引入任何第三方运行时依赖（见 pyproject.toml 的 dependencies = []）。
可选 extras：protobuf（Linux 原生帧序列化）、local-bge-cpu / local-bge-gpu（本地向量嵌入）。
开发与验证工具：pytest>=8,<10、ruff>=0.6、mypy>=1.10，由 environment.yml 提供。
Web 前端依赖（用于可视化实验台）：Node.js 20+，npm 10+

构建与安装方法

1. 主机开发环境配置（推荐方式）

# 1. 克隆代码仓库
git clone <repository-url>
cd OpenMemory

# 2. 基于 Conda 安装一站式开发环境（固定 Python 3.11 与必要工具链）
conda env create -f environment.yml
conda activate openmemory

# 3. 以可编辑模式安装当前核心 Python 包
pip install -e .

# 4. 运行仓库级静态规范校验（验证 Shell 语法、环境配置与 Markdown 规范）
./scripts/verify

2. Web 可视化工作台构建（可选）

本地实验台已内置预构建的独立单页运行资产（开箱即用，无需 Node 依赖即可由 Python 服务直接托管）。如需在开发模式下对 Web 端进行二次开发或重新编译：

# 安装 Web 依赖
npm ci --prefix web

# 运行前端测试与类型检查
npm test --prefix web
npm run lint --prefix web

# 重新构建静态包并自动同步至 Python 包资产目录
npm run build --prefix web

运行方法

系统提供本地离线回放体验、交互式实验台（Studio）与 openEuler 官方容器复现三种运行入口：

1. 本地确定性基准回放

在已激活的 openmemory 环境中，运行两大主要连续协作任务：

# 运行源码故障影响分析工作流（Codebase Incident & Repair）
openmemory run --stage diagnostic examples/scenarios/codebase-incident-repair-continuous.json \
  --backend replay --modes B0 B1 B2 B3 --repeat 1 --memory-policy clean --vector-capability enabled

# 运行日志与遥测诊断工作流（Log & Telemetry Diagnosis）
openmemory run --stage diagnostic examples/scenarios/telemetry-diagnosis-continuous.json \
  --backend replay --modes B0 B1 B2 B3 --repeat 1 --memory-policy clean --vector-capability enabled

# 运行十轮连续长程协作稳定性验证
openmemory run --stage diagnostic examples/scenarios/stability-10-round.json \
  --backend mock --modes B3 --repeat 1 --memory-policy clean --vector-capability enabled

评测结果将输出至 benchmarks/results/<scenario_id>/<run_id>/，包含各模式对比摘要（summary/summary.md）、事件轨迹（trace.jsonl）、四层记账数据（metrics.json）与执行结果（result.json）。

2. 启动本地交互式实验台

# 启动本地服务（默认监听 127.0.0.1:8765）
openmemory studio --host 127.0.0.1 --port 8765

浏览器访问 http://127.0.0.1:8765/studio，可自由切换任务、调整输入参数、实时触发 B0/B2/B3 模式对比，并查看状态复用与计算省略的图形化时序。

3. openEuler 24.03-LTS-SP3 官方容器复现

# 构建 openEuler 官方开发容器镜像
./scripts/dev-env.sh build

# 进入容器交互终端
./scripts/dev-env.sh shell

# 在容器内部执行环境配置与工具链验证
./scripts/dev-env.sh verify

# 执行 openEuler 官方凭证封装自动化评测
./scripts/verify-openeuler-evidence.sh --inside-container \
  --output-dir benchmarks/results/verify-run \
  --skip-live-smoke --vector-capability enabled

测试方法与测试材料说明

OpenMemory 建立了严格分层的自动化测试套件：可执行的单元、集成与端到端测试位于 tests/ 目录下，而 benchmark 的场景、语料、oracle 与 replay 夹具归档于 benchmarks/。

1. `tests/` 测试材料结构与分类说明

测试目录	包含材料与验证目标	推荐执行命令
`tests/unit/`	单元测试：覆盖类型化协议契约（`protocol.py`）、存储引擎（`stores/`）、任务图调度器（`coordinator.py` / `task_graph.py`）、C2 状态算子因果移除、C3 依赖有效性校验、余弦相似度特征重建及安全脱敏逻辑	`pytest tests/unit -q`
`tests/integration/`	集成测试：验证 Coordinator 跨端点多角色协同、Linux 内存映射跨进程传输、Unix 域套接字租约管理、四层记账凭证一致性及端点进程池跨轮复用	`pytest tests/integration -q`
`tests/e2e/`	端到端与文档一致性测试：验证全链路确定性回放、已文档化命令路径一致性（`test_documented_replay_path.py`）、长程交互稳定性及评审证明包构建	`pytest tests/e2e -q`
`tests/evidence/`	评审证据投影：已固化的冻结候选只读证据镜像（含评分卡、证明清单摘要及轻量看板），供评审专家在免运行环境下直接核对数据真实性	静态查阅 / 离线核验

2. 测试执行方法

# 1. 运行核心单元测试
pytest tests/unit -q

# 2. 运行跨模块集成测试
pytest tests/integration -q

# 3. 运行端到端与文档化路径一致性验证
pytest tests/e2e -q

# 4. 执行全量自动化测试套件（当前基准：1239 passed, 1 skipped）
pytest tests/unit tests/integration tests/e2e -q

已知限制与客观边界

项目秉持严谨的工程与科学态度，主动披露系统的适用边界与技术局限：

业务场景覆盖范围：当前 Studio 实验台聚焦于两组声明好的标准长程协作场景，用于隔离与测量系统机制收益，暂不支持向任意未知业务代码仓库或无格式日志流的通用一键迁移；
离线回放与在线模型差异：Replay 与 Mock 模式用于严格验证系统功能完整性、状态流转与执行判定逻辑，不能直接推算线上真实大模型的质量分布或商用 API token 节省；
平台与硬件性能边界：当前候选记录确认了容器化 openEuler 24.03-LTS-SP3 linux/amd64（x86_64）运行环境，但没有记录物理宿主机架构；该结果不能证明原生 x86_64 物理机性能；
性能与复用成本边界：单次 stage=diagnostic Replay 汇总（每个模式一条序列）记录的 B0→B3 elapsed_ms 增量为 Codebase +7.702%、Telemetry +27.889%，不代表在线延迟。六次配对 host-live 测量中的完整本地 B2−B3 净差中位数分别为 −85.222 ms 与 −245.045 ms，尚未证明稳定净节约；详见技术报告；
外部向量检索依赖边界：本地状态通道仅证明 Linux 本机二进制数据安全传输与进程隔离消费，不代表跨主机分布式共享内存，亦不代表已解决外部向量嵌入模型本身的语义表征质量问题。

可查验的候选证据

仓库提交的候选证据投影位于 tests/evidence/final-freeze-20261006-longer-wait/，其中包含离线评审看板。当前工作区的完整候选结果位于 benchmarks/results/final-freeze-20261006-longer-wait/；该目录由 .gitignore 排除，不随克隆分发。benchmarks/proof/ 是最近一次 promotion 的规范证据，不绑定本次候选。最终打包工具 scripts/render-final-submission.py 要求证据根目录不存在或为空，并在该根目录下写出 docs/submission/reviewer-evidence-map.md 描述的平铺 tests/evidence/ 布局；当前仓库跟踪的 tests/evidence/final-freeze-20261006-longer-wait/ 即为面向本次候选的评审投影。

正式评审证据与量化指标

本次工程候选绑定源码提交版本 a2f8da90c443ddf8b4b905bd0e6da893d22cfd04（a2f8da9）及在线采集 efcfab6a-a36b-4562-bf5d-bea5f6a836f3。完整结果位于本地忽略目录 benchmarks/results/final-freeze-20261006-longer-wait/；仓库内可查验的脱敏投影位于 tests/evidence/final-freeze-20261006-longer-wait/。

总评测样本量：两组任务各完成 36 条序列，全库共计完成 72 条完整十轮序列（720 个交互轮次）；
任务质量 Oracle 检验：两组任务各自的主实验与状态关闭（OFF）消融合计 oracle 均通过 240/240（两任务累计 480/480 轮 100% 通过）；
跨轮状态因果消融（C2）：状态开启/关闭（ON/OFF）因果校验两组各为 60/60；
计算复用正确性（C3）：两组各达成 42 次有效复用、12 次必要重算、0 次错误复用；
容器自动化测试覆盖：openEuler 目标容器内全量测试套件通过 1239 passed, 1 skipped；
证明清单与评分卡状态：competition-proof-manifest.json 为 passed，competition-scorecard.json 为 evidence-supported。

演示材料按 presentation/ 中的要求准备，录制路线见演示脚本。openmemory demo-video 为可选的短版素材生成工具。以下命令用于候选归档审计流程：

openmemory submission-audit --proof-manifest benchmarks/results/<candidate>/competition-proof-manifest.json \
  --video benchmarks/results/<candidate>/demo/openmemory-competition-demo.mp4 \
  --output-dir benchmarks/results/<candidate>/submission-audit --require-ready

代码仓库结构与核心交付资产

OpenMemory 遵循模块职责解耦与清晰的工程工件组织，核心代码、交互平台、自动化测试套件与主要交付资产分布如下：

OpenMemory/
├── src/                              # 核心系统实现（类型化协议契约、双平面存储引擎、状态调度器）
├── web/                              # 本地交互式 Studio 实验台单页前端（React / TypeScript）
├── tests/                            # 分层自动化测试套件（unit/、integration/、e2e/）与离线评审证据镜像
├── benchmarks/                       # 标准协作评测工作流、真实基准与冻结凭证
├── demo/                             # 可运行复现脚本与一键验证入口
├── presentation/                     # 答辩演示材料目录与本地展示素材
├── docs/                             # 体系化设计文档、技术报告与官方交付文件
│   ├── 项目说明书.pdf                # 完整技术说明与架构实现详述
│   ├── 项目创新说明.pdf              # 三大核心创新点与学术/工业界对比论证
│   ├── 成员分工及主要贡献说明.pdf    # 研发分工与贡献权重
│   └── 人工智能及第三方工具使用说明.pdf # 工具真实使用披露与安全边界
├── README.md                         # 项目主说明与快速复现指引
└── 作品原创承诺书.pdf                # 赛事原创合规签署材料

项目正式提交材料采用 PDF 格式，技术结论与正式评测数据均严格绑定冻结源码版本 a2f8da9。演示材料规格与本地回放指引详见演示材料说明与可运行 Demo 指引。

体系化文档与延伸导航

维护与知识导航：索引赛事要求、当前系统架构、决策记录（Decision Notes）、排障方案（Solutions）与收尾交接。
赛题规范要求（SPEC.md）：对照赛题各项要求、评分标准细则与平台交付约束。
技术报告与提交说明：面向技术评审的详细材料。
系统架构文档（ARCHITECTURE.md）与运行时设计说明：阐述底层分层机制与执行原理。
贡献指南（CONTRIBUTING.md）：说明开发流程、分支规范与本地合规检查。
系统重评估报告：保存较早阶段的技术取舍、实验对比与边界；最新候选状态见技术报告。
决赛报告 PDF：项目说明书、项目创新说明与工具使用说明。评分字段映射契约见 renderer-input-map.json。
可运行 Demo：提供完备可复现的离线回放与 Mock 验证入口；真实在线测量数据均可经由评测产物严格回溯。
演示视频高清版：可在夸克浏览器/夸克网盘中下载播放。
评审核对证据：本次候选的脱敏投影位于 tests/evidence/final-freeze-20261006-longer-wait/；benchmarks/proof/ 保留最近一次 promotion 的证据，与本次候选版本不同。全新克隆不包含被忽略的 benchmarks/results/ 原始运行目录。