memsuOS

Auditable and governable infrastructure for autonomous agent organizations.

memsuOS 是一个面向自治 Agent 组织的开放协议内核。它允许模型提出新的组织形态、角色关系、讨论机制、工作流和执行意图，同时把事实声明、权限、预算、工具、数据和外部影响放进可审计的治理边界。

它不是固定的 Planner / Critic / Executor 流程，也不是一个低代码 Agent 编排器。项目当前处于 0.1.x 研究与工程验证阶段，重点是协议、账本、治理、运行时边界和可观测性，而不是生产级外部动作执行。

授权说明： 本仓库以源码可见（source-available）方式发布，并非 OSI 定义的开源软件。自然人可用于个人非商业目的；任何商业用途，以及代表公司、组织、政府机构或其他法人实体的使用，均须事先取得书面授权。详见 LICENSE。

界面预览

Organization Observatory

从 JSONL ledger 派生组织、治理、runtime、讨论和扩展信号；页面只读，不修改账本。

Multi-Agent Flow Canvas

展示模型声明或事件派生的多 Agent 拓扑。图中的组织形态是开放协议对象，不是内核允许列表。

Runtime Replay

回放 action、checkpoint、completion 和原始事件，帮助定位组织提案如何经过治理并进入 runtime。

为什么需要 memsuOS

自治 Agent 系统通常同时面对两个相反的要求：

• 模型需要足够开放的表达空间，才能提出早期工程师没有预设过的组织方式。
• 真实动作又必须受控，不能因为模型自称有能力、多个 Agent 达成共识或历史评分较高就自动获得权限。

memsuOS 将两者拆开：

开放表达 != 事实
事实或共识 != 权限
权限 != 已执行
已执行 != 已验证成功

核心闭环是：

User Goal
  -> ProtocolArtifact
  -> AuditProjection
  -> ProtocolEvent ledger
  -> Claim Firewall
  -> GovernanceActionSpec
  -> AuthorizationDecision
  -> RuntimeAdapter
  -> RuntimeEvent
  -> Reflection / advisory memory
  -> Derived views

工程原则可以概括为：

strong envelope
weak payload
strong projection
strong governance

协议 envelope、引用、事件和治理契约保持稳定；artifact payload 对未知字段、未知类型和未来组织形态保持开放。

零号原则

任何例子、默认 schema、测试、目录、参考角色、评测分数和历史范式，都不得成为模型智能的表达上限。

因此：

• roundtable、parliament、supervisor、context-holder 只是候选形式。
• GoalSpec、OrgSpec、DiscussionSpec、WorkflowSpec 等是审计适配器，不是合法性枚举。
• 未知 artifact、payload 字段、event type、action class 和组织关系可以被保留和扩展。
• LangGraph 是可选 runtime adapter，不是 memsuOS 协议本体。
• 记忆、声誉、信息素、共识、评测分数和模型自述都不能自行授权。
• 会改变文件、工具、数据库、网络、策略或外部系统的动作，必须先经过治理决策。

当前实现

开放协议与事件账本

• ProtocolArtifact、AuditProjection、ProtocolEvent、ActorRef、ArtifactRef。
• 开放 payload 和容错投影，保留未知表达。
• append-only JSONL ledger 作为事实源；UI、报告和工作流视图均为派生结果。

治理与 Claim Firewall

• GovernanceActionSpec 将模型意图归一化为可治理动作。
• PolicyDocument 使用不可变策略快照。
• AuthorizationDecision 支持 approve、simulate_only、deny、escalate 和 request_revision。
• Claim Firewall 记录 claim.proposed、上下文包、治理依据检查、传播阻断和验证事件。
• 未验证或有争议的高影响声明不能进入 confirmed context，也不能作为治理授权依据。

Runtime 与动态工作流

• LocalSimulator：默认无外部 runtime 副作用。
• LangGraphAdapter：可选的 LangGraph 执行适配层。
• WorkflowSpec、WorkflowInvocation、WorkflowFrame、RouteDecision。
• LocalWorkflowRouter：只评估声明式 JSON predicate，不执行任意代码。
• 显式开启 --allow-session-artifact-write 时，只允许写当前 session 目录中的 execution-result.md。

模型与 Agent 适配

• 本地安全 smoke：mock。
• API：OpenAI Responses、OpenAI-compatible、DeepSeek、Kimi、Kimi built-in web search、Ark Plan profile family。
• 本地 CLI / SDK：Kimi CLI、Codex CLI、Codex SDK、AGY CLI。
• 实验入口：Codex-like endpoint 和自定义本地 provider profile。
• MiMo 当前在代码中禁用，只保留历史验证记录。

选择真实 API 或 CLI provider 会产生相应的网络请求或本地子进程；“无外部副作用”描述的是默认 runtime 动作边界，不代表真实模型调用不联网。

观测与研究机制

• v1 event replay、v2 Organization Observatory、独立 Multi-Agent Flow Canvas。
• SVM-24 本地 swarm：蜂群对象、信息素评分、quorum gate 和可解释报告。
• EACN-lite：能力注册、任务市场、竞标、裁决、声誉信号和派生视图。
• Fusion：多模型 work / review / revise、治理 profile、bounded fanout 和聚合。
• NFugu、LLM Council、CodeFuse / DeepSWE：研究与评测 harness，不是默认产品流程。
• Codex 插件：plugins/memsuos 和 plugins/fusion。

快速开始

要求 Python 3.11+。核心包没有必选第三方运行时依赖；LangGraph 是可选依赖。

git clone https://github.com/susyimes/memsuOS.git
cd memsuOS

python -m venv .venv
.\.venv\Scripts\Activate.ps1
python -m pip install --upgrade pip
python -m pip install -e .

Linux / macOS 激活虚拟环境：

source .venv/bin/activate

如需 LangGraph adapter：

python -m pip install -e ".[langgraph]"

运行一个不需要 API key 的开放组织 session：

python -B scripts/run_open_org_session.py `
  --goal "设计一个只读组织来审查发布计划" `
  --provider mock `
  --runtime local `
  --out-dir .memsuos/sessions/quickstart `
  --max-artifacts 1

输出目录包含：

• open-org-session.jsonl：append-only 事件账本。
• open-org-session-summary.json：机器可读摘要。
• open-org-session-report.md：面向人的报告。
• input-goal.md：本次输入目标。

.memsuos/ 是本地运行与评测目录，已被 Git 忽略。

使用示例

仓库提供了一组不需要 API key 的安全 samples：

.\examples\run-safe-samples.ps1

这条命令会依次运行：

• 一个以 examples/goals/release-readiness-review.md 为输入的 mock open-org session。
• roundtable、parliament vote 和 self-organizing discussion 三种参考组织探针。
• 一个两轮 reference supervision loop。
• 一个 deterministic local swarm。
• 一个 local EACN-lite capability matching run。

这些模式只是观察样例，不是内核允许列表。所有产物写入 .memsuos/examples/<timestamp>/。更多单独命令、预期产物和 replay 用法见 examples/README.md。

在 Codex App 中使用

仓库已经附带 Codex App 所需的 marketplace 和插件：

.agents/plugins/marketplace.json
plugins/memsuos
plugins/fusion

克隆仓库后，在仓库根目录注册 marketplace 并安装 memsuOS：

codex plugin marketplace add .
codex plugin add memsuos@memsuos-local

可选安装 Fusion：

codex plugin add fusion@memsuos-local

安装后在 Codex App 中打开这个 memsuOS checkout，并新建一个任务以加载插件。可以直接输入：

用 memsuOS 启动一个不需要 API key 的 mock open-org smoke，
完成后汇总 artifact、授权、runtime、claim firewall 和产物路径。

更多可复制提示词见 Codex App 提示词示例。插件只是 Codex App 的入口层：运行时仍来自当前 checkout，.memsuos/ 与 provider 凭据仍保持本地。

打开观测界面

使用刚才生成的 ledger：

python -B scripts/serve_interaction_replay.py `
  .memsuos/sessions/quickstart/open-org-session.jsonl `
  --ui-version v2 `
  --open

服务默认监听 127.0.0.1:8765：

• http://127.0.0.1:8765/：v1 event replay。
• http://127.0.0.1:8765/v2：Organization Observatory。
• http://127.0.0.1:8765/v2/flow：独立 Multi-Agent Flow Canvas。

复现 README 中的 fanout-and-synthesize 演示：

python -B scripts/create_fanout_synthesize_replay.py `
  --out-dir .memsuos/evals/fanout-synthesize-demo

python -B scripts/serve_interaction_replay.py `
  .memsuos/evals/fanout-synthesize-demo/fanout-synthesize.jsonl `
  --ui-version v2 `
  --open

该演示只生成本地协议事件和文档，不调用真实模型。

使用真实模型

真实 provider 的凭据应通过进程环境变量或本地配置提供：

.memsuos/model-providers.local.json

这个文件和所有 *.local.json 均被 Git 忽略。不要把 API key 写入 README、测试、issue、日志或可提交配置。

OpenAI Responses 示例：

$env:OPENAI_API_KEY = "<your-key>"
$env:OPENAI_MODEL = "<model-name>"

python -B scripts/run_open_org_session.py `
  --goal "提出一个可审计的只读研究组织" `
  --provider openai `
  --runtime local `
  --out-dir .memsuos/sessions/openai-example `
  --max-artifacts 1

Ark Plan 示例：

$env:ARK_API_KEY = "<your-key>"

python -B scripts/run_open_org_session.py `
  --goal "提出一个最小自治组织，并明确治理边界" `
  --provider ark-plan-deepseek `
  --runtime local `
  --out-dir .memsuos/sessions/ark-example `
  --max-artifacts 1

自定义 OpenAI-compatible endpoint 可使用：

MEMSUOS_MODEL_API_KEY
MEMSUOS_MODEL_BASE_URL
MEMSUOS_MODEL_NAME

然后将 --provider 设为 compatible。Provider 是否“已配置”不等于运行健康；应检查产物是不是实际模型 artifact，而不是 ModelFailureObservation。

安全边界

默认 LocalSimulator 不执行 shell、git、数据库、任意文件写入或模型提出的网络动作。

只有显式传入：

--allow-session-artifact-write

才会开放这一条本地能力：

session_artifact_write
  -> 当前 session 输出目录
  -> execution-result.md

文件名必须是 basename，解析后的父目录必须仍是当前 session 目录。

此外：

• prior_experience 默认关闭，只有传入 --experience-path 才会进入上下文。
• memory、reputation、pheromone、consensus 和 evaluation score 始终是 advisory signal。
• UI 是只读派生视图，不改写 ledger，也不发出治理动作。
• Claim Firewall 阻断的是不受支持声明的传播与权限升级，不删除原始 artifact。
• --allow-autostart 只允许本地 simulation；不会授予 tool call、policy change、任意文件、remote 或外部副作用。

本地机制示例

运行 deterministic swarm smoke：

python -B scripts/run_local_swarm.py `
  --goal "比较三个候选方案并保留少数意见" `
  --out-dir .memsuos/swarm-runs/example

运行 EACN-lite smoke：

python -B scripts/run_local_eacn.py `
  --goal "为一个只读研究任务匹配能力并裁决结果" `
  --out-dir .memsuos/eacn-runs/example

这些 runner 用于验证协议、治理和报告链路，不代表生产级分布式执行系统。

项目结构

src/autonomous_org/
  core/          # 开放协议 envelope、事件、引用与不变量
  protocol/      # 审计投影、默认适配器与协议扩展
  claims/        # Claim Firewall、证据、传播和上下文包
  governance/    # 动作归一化、策略快照、授权和修复
  intelligence/  # 模型适配、Agent 路由、提案与修复服务
  runtime/       # LocalSimulator 与可选 LangGraphAdapter
  workflow/      # 动态 workflow 协议、frame、route 和 router
  ledger/        # append-only JSONL ledger
  memory/        # advisory memory 与 prior experience
  views/         # replay、observatory、workflow 和 EACN 派生视图
  swarm/         # 本地蜂群协议与 quorum gate
  eacn/          # EACN-lite 能力网络
  fusion/        # Fusion coordination 与 NFugu 数据模型
  evaluation/    # 质量、组织、治理修复和监督评测

scripts/         # session、UI、smoke、评测、对比和研究入口
plugins/         # memsuOS / Fusion Codex 插件
examples/        # 可运行 samples、目标文件与 Codex App 提示词
.agents/         # Codex App marketplace
docs/            # PRD、技术设计、实现记录与研究文档
tests/           # 协议、治理、runtime、UI 和 runner 回归测试

测试

运行完整测试：

python -B -m unittest discover -s tests

常用聚焦测试：

python -B -m unittest tests.test_open_org_session
python -B -m unittest tests.test_claim_firewall
python -B -m unittest tests.test_runtime_adapter_contract
python -B -m unittest tests.test_interaction_replay
python -B -m unittest tests.test_workflow_protocol tests.test_workflow_router
python -B -m unittest tests.test_swarm_mechanism tests.test_eacn_lite

文档导航

• 项目规格索引
• 自治 Agent 组织 PRD
• 技术设计
• 基础实现
• Claim Firewall 实现
• 动态 Workflow
• UI v2 方向
• Swarm 机制
• EACN-lite
• Fusion 自协调
• NFuguMode

发布与授权说明

• 仓库不会提交 .memsuos/、*.local.json、API key 或本地运行产物。
• 若 fork 或公开历史分支，请同时审计所有 refs，而不只是 main。
• 真实 provider 的输出和第三方服务行为应在各自边界内验证。
• 本仓库采用自定义的个人非商业许可证，不是 OSI 批准的开源许可证。
• 自然人的个人、教育、实验或研究性非商业使用可以依照许可证进行。
• 商业使用和任何组织用途均须事先取得版权持有人的书面授权或单独商业许可证。

License

本项目依据 memsuOS Personal Non-Commercial License 1.0 发布。自然人可在个人非商业范围内使用、研究、修改和按相同条款非商业再分发；商业使用及组织使用需要事先书面授权。