diff --git a/README.md b/README.md index 9f2ace01..424bee6a 100644 --- a/README.md +++ b/README.md @@ -1,7 +1,7 @@

- Molecule AI Icon Logo + Molecule AI

@@ -39,8 +39,8 @@ Workspace Runtime

-[![Deploy on Railway](https://railway.app/button.svg)](https://railway.app/new/template?template=https://git.moleculesai.app/molecule-ai/molecule-monorepo) -[![Deploy to Render](https://render.com/images/deploy-to-render-button.svg)](https://render.com/deploy?repo=https://git.moleculesai.app/molecule-ai/molecule-monorepo) +[![Deploy on Railway](https://railway.app/button.svg)](https://railway.app/new/template?template=https://git.moleculesai.app/molecule-ai/molecule-core) +[![Deploy to Render](https://render.com/images/deploy-to-render-button.svg)](https://render.com/deploy?repo=https://git.moleculesai.app/molecule-ai/molecule-core)
@@ -53,8 +53,8 @@ Molecule AI is the most powerful way to govern an AI agent organization in produ It combines the parts that are usually scattered across demos, internal glue code, and framework-specific tooling into one product: - one org-native control plane for teams, roles, hierarchy, and lifecycle -- one runtime layer that lets LangGraph, DeepAgents, Claude Code, CrewAI, AutoGen, and OpenClaw run side by side -- one memory model that keeps recall, sharing, and skill evolution aligned with organizational boundaries +- one runtime layer that lets **eight** agent runtimes — LangGraph, DeepAgents, Claude Code, CrewAI, AutoGen, **Hermes**, **Gemini CLI**, and OpenClaw — run side by side behind one workspace contract +- one memory model that keeps recall, sharing, and skill evolution aligned with organizational boundaries (Memory v2 backed by pgvector for semantic recall) - one operational surface for observing, pausing, restarting, inspecting, and improving live workspaces Most teams can build a workflow, a strong single agent, a coding agent, or a custom multi-agent graph. @@ -75,7 +75,7 @@ You do not wire collaboration paths by hand. Hierarchy defines the default commu ### 3. Runtime choice stops being a dead-end decision -LangGraph, DeepAgents, Claude Code, CrewAI, AutoGen, and OpenClaw can all plug into the same workspace abstraction. Teams can standardize governance without forcing every group onto one runtime. +LangGraph, DeepAgents, Claude Code, CrewAI, AutoGen, Hermes, Gemini CLI, and OpenClaw can all plug into the same workspace abstraction. Teams can standardize governance without forcing every group onto one runtime. ### 4. Memory is treated like infrastructure @@ -117,6 +117,8 @@ Molecule AI is not trying to replace the frameworks below. It is the system that | **Claude Code** | Shipping on `main` | Real coding workflows, CLI-native continuity | Secure workspace abstraction, A2A delegation, org boundaries, shared control plane | | **CrewAI** | Shipping on `main` | Role-based crews | Persistent workspace identity, policy consistency, shared canvas and registry | | **AutoGen** | Shipping on `main` | Assistant/tool orchestration | Standardized deployment, hierarchy-aware collaboration, shared ops plane | +| **Hermes 4** | Shipping on `main` | Hybrid reasoning, native tools, json_schema (NousResearch/hermes-agent) | Option B upstream hook, A2A bridge to OpenAI-compat API, multi-provider provider derivation | +| **Gemini CLI** | Shipping on `main` | Google Gemini CLI continuity | Workspace lifecycle, A2A, hierarchy-aware collaboration, shared ops plane | | **OpenClaw** | Shipping on `main` | CLI-native runtime with its own session model | Workspace lifecycle, templates, activity logs, topology-aware collaboration | | **NemoClaw** | WIP on `feat/nemoclaw-t4-docker` | NVIDIA-oriented runtime path | Planned to join the same abstraction once merged; not yet part of `main` | @@ -182,9 +184,10 @@ The result is not just “an agent that learns.” It is **an organization that ## What Ships In `main` -### Canvas +### Canvas (v4) - Next.js 15 + React Flow + Zustand +- **warm-paper theme system** — light / dark / follow-system, SSR cookie + nonce'd boot script + ThemeProvider; terminal + code surfaces stay dark unconditionally - drag-to-nest team building - empty-state deployment + onboarding wizard - template palette @@ -193,8 +196,9 @@ The result is not just “an agent that learns.” It is **an organization that ### Platform -- Go/Gin control plane -- workspace CRUD and provisioning +- Go 1.25 / Gin control plane (80+ HTTP endpoints + Gorilla WebSocket fanout) +- workspace CRUD and provisioning (pluggable Provisioner — Docker locally, EC2 + SSM in production) +- **A2A response path is a typed discriminated union (RFC #2967)** — frozen dataclasses + total parser; 100% unit + adversarial fuzz coverage - registry and heartbeats - browser-safe A2A proxy - team expansion/collapse @@ -204,10 +208,10 @@ The result is not just “an agent that learns.” It is **an organization that ### Runtime -- unified `workspace/` image -- adapter-driven execution +- unified `workspace/` image; thin AMI in production (us-east-2) +- adapter-driven execution across **8 runtimes** (Claude Code, Hermes, Gemini CLI, LangGraph, DeepAgents, CrewAI, AutoGen, OpenClaw) - Agent Card registration -- awareness-backed memory integration +- awareness-backed memory integration; **Memory v2 backed by pgvector** for semantic recall - plugin-mounted shared rules/skills - hot-reloadable local skills - coordinator-only delegation path @@ -221,6 +225,21 @@ The result is not just “an agent that learns.” It is **an organization that - runtime tiers - direct workspace inspection through terminal and files +### SaaS (via [`molecule-controlplane`](https://github.com/Molecule-AI/molecule-controlplane)) + +- multi-tenant on AWS EC2 + Neon (per-tenant Postgres branch) + Cloudflare Tunnels (per-tenant, no public ports) +- WorkOS AuthKit + Stripe Checkout + Customer Portal +- AWS KMS envelope encryption (DB / Redis connection strings); AWS Secrets Manager for tenant bootstrap +- `tenant_resources` audit table + 30-min boot-event-aware reconciler — every CF / AWS lifecycle event recorded, claim vs live state diffed + +### Bring your own Claude Code session (via [`molecule-mcp-claude-channel`](https://github.com/Molecule-AI/molecule-mcp-claude-channel)) + +- Claude Code plugin that bridges Molecule A2A traffic into a local Claude Code session via MCP +- subscribe to one or more workspaces; peer messages surface as conversation turns; replies route back through Molecule's A2A +- no tunnel, no public endpoint — the plugin self-registers each watched workspace as `delivery_mode=poll` and long-polls `/activity?since_id=…` +- multi-tenant friendly: one plugin install can watch workspaces across multiple Molecule tenants (`MOLECULE_PLATFORM_URLS` per-workspace) +- install via the standard marketplace flow: `/plugin marketplace add Molecule-AI/molecule-mcp-claude-channel` → `/plugin install molecule-channel@molecule-mcp-claude-channel` + ## Built For Teams That Need More Than A Demo Molecule AI is especially strong when you need to run: @@ -233,24 +252,30 @@ Molecule AI is especially strong when you need to run: ## Architecture ```text -Canvas (Next.js :3000) <--HTTP / WS--> Platform (Go :8080) <---> Postgres + Redis - | | - | +--> Docker provisioner / bundles / templates / secrets +Canvas (Next.js 15, warm-paper :3000) <--HTTP / WS--> Platform (Go 1.25 :8080) <---> Postgres + Redis + | | + | +--> Provisioner: Docker (local) / EC2 + SSM (prod) + | +--> bundles · templates · secrets · KMS | - +-------------------- shows --------------------> workspaces, teams, tasks, traces, events + +------------------------- shows ------------------------> workspaces, teams, tasks, traces, events -Workspace Runtime (Python image with adapters) - - LangGraph / DeepAgents / Claude Code / CrewAI / AutoGen / OpenClaw - - Agent Card + A2A server - - heartbeat + activity + awareness-backed memory +Workspace Runtime (Python ≥3.11, image with adapters) + - 8 adapters: LangGraph / DeepAgents / Claude Code / CrewAI / AutoGen / Hermes / Gemini CLI / OpenClaw + - Agent Card + A2A server (typed-SSOT response path, RFC #2967) + - heartbeat + activity + awareness-backed memory (Memory v2 — pgvector semantic recall) - skills + plugins + hot reload + +SaaS Control Plane (molecule-controlplane, private) + - per-tenant EC2 + Neon (Postgres branch) + Cloudflare Tunnel + - WorkOS · Stripe · KMS · AWS Secrets Manager + - tenant_resources audit + 30-min reconciler ``` ## Quick Start ```bash -git clone https://git.moleculesai.app/molecule-ai/molecule-monorepo.git -cd molecule-monorepo +git clone https://git.moleculesai.app/molecule-ai/molecule-core.git +cd molecule-core cp .env.example .env # Defaults boot the stack locally out of the box. See .env.example for @@ -303,7 +328,11 @@ Then open `http://localhost:3000`: ## Current Scope -The current `main` branch already includes the core platform, canvas, memory model, six production adapters, skill lifecycle, and operational surfaces. Adjacent runtime work such as **NemoClaw** remains branch-level until merged, and this README keeps that distinction explicit on purpose. +The current `main` branch ships the core platform, Canvas v4 (warm-paper themed), Memory v2 (pgvector semantic recall), the typed-SSOT A2A response path (RFC #2967), **eight production adapters** (Claude Code, Hermes, Gemini CLI, LangGraph, DeepAgents, CrewAI, AutoGen, OpenClaw), skill lifecycle, and operational surfaces. + +The companion private repo [`molecule-controlplane`](https://github.com/Molecule-AI/molecule-controlplane) provides the SaaS surface — multi-tenant orchestration on EC2 + Neon + Cloudflare Tunnels, KMS envelope encryption, WorkOS auth, Stripe billing, and a `tenant_resources` audit table with a 30-min reconciler. + +Adjacent runtime work such as **NemoClaw** remains branch-level until merged, and this README keeps that distinction explicit on purpose. ## License diff --git a/README.zh-CN.md b/README.zh-CN.md index 52ca6fb3..2b73208b 100644 --- a/README.zh-CN.md +++ b/README.zh-CN.md @@ -1,7 +1,7 @@

- Molecule AI 图案 Logo + Molecule AI

@@ -52,8 +52,8 @@ Molecule AI 是目前最强的 AI Agent 组织治理方案之一，用来把 age 它把过去分散在 demo、内部胶水代码和各类 framework 私有工具里的关键能力，收敛成一个产品： - 一套组织原生 control plane，管理团队、角色、层级和生命周期 -- 一套 runtime abstraction，让 LangGraph、DeepAgents、Claude Code、CrewAI、AutoGen、OpenClaw 并存运行 -- 一套与组织边界对齐的 memory 模型，把 recall、sharing 和 skill evolution 放进同一体系 +- 一套 runtime abstraction，让 **8 个** agent runtime —— LangGraph、DeepAgents、Claude Code、CrewAI、AutoGen、**Hermes**、**Gemini CLI**、OpenClaw —— 共用一套 workspace 契约 +- 一套与组织边界对齐的 memory 模型，把 recall、sharing 和 skill evolution 放进同一体系（Memory v2 由 pgvector 支撑语义召回） - 一套面向线上 workspace 的运维面，统一完成观测、暂停、重启、检查和持续改进 今天很多团队能做好 workflow、单 agent、coding agent，或者自定义 multi-agent graph 中的一种。 @@ -74,7 +74,7 @@ Molecule AI 填的就是这个空白。 ### 3. Runtime 选择不再是死路 -LangGraph、DeepAgents、Claude Code、CrewAI、AutoGen、OpenClaw 都可以挂到同一个 workspace abstraction 下。团队可以统一治理方式，而不必统一到底层 runtime。 +LangGraph、DeepAgents、Claude Code、CrewAI、AutoGen、Hermes、Gemini CLI、OpenClaw 都可以挂到同一个 workspace abstraction 下。团队可以统一治理方式，而不必统一到底层 runtime。 ### 4. Memory 被当成基础设施来做 @@ -116,6 +116,8 @@ Molecule AI 并不是要替代下面这些 framework，而是把它们纳入更 | **Claude Code** | `main` 已支持 | 真实编码工作流、CLI-native continuity | 安全 workspace 抽象、A2A delegation、组织边界、共享 control plane | | **CrewAI** | `main` 已支持 | 角色型 crew 模式清晰 | 持久 workspace 身份、统一策略、共享 Canvas 和 registry | | **AutoGen** | `main` 已支持 | assistant/tool orchestration | 统一部署、层级协作、共享运维平面 | +| **Hermes 4** | `main` 已支持 | 混合推理、原生工具调用、json_schema 输出（NousResearch/hermes-agent） | Option B 上游 hook、A2A 桥接 OpenAI 兼容 API、多 provider 自动派生 | +| **Gemini CLI** | `main` 已支持 | Google Gemini CLI 持续会话 | workspace 生命周期、A2A、层级感知协作、共享运维平面 | | **OpenClaw** | `main` 已支持 | CLI-native runtime，自有 session 模型 | workspace 生命周期、templates、activity logs、拓扑感知协作 | | **NemoClaw** | `feat/nemoclaw-t4-docker` 分支 WIP | NVIDIA 方向 runtime 路线 | 计划并入同一抽象层，但当前还不是 `main` 已合并能力 | @@ -181,9 +183,10 @@ Molecule AI 并不是要替代下面这些 framework，而是把它们纳入更 ## `main` 分支已经具备什么 -### Canvas +### Canvas（v4） - Next.js 15 + React Flow + Zustand +- **warm-paper 主题系统** —— light / dark / 跟随系统；SSR cookie + nonce'd boot 脚本 + ThemeProvider；终端与代码面板始终保持深色 - drag-to-nest 团队构建 - empty state + onboarding wizard - template palette @@ -192,8 +195,9 @@ Molecule AI 并不是要替代下面这些 framework，而是把它们纳入更 ### Platform -- Go/Gin control plane -- workspace CRUD 和 provisioning +- Go 1.25 / Gin control plane（80+ HTTP 端点 + Gorilla WebSocket fanout） +- workspace CRUD 和 provisioning（可插拔 Provisioner —— 本地 Docker、生产 EC2 + SSM） +- **A2A 响应路径已收敛为类型化的判别联合（RFC #2967）** —— 冻结 dataclass + 全量 parser；100% 单元测试 + 对抗性 fuzz 覆盖 - registry 与 heartbeat - 浏览器安全的 A2A proxy - team expansion/collapse @@ -203,10 +207,10 @@ Molecule AI 并不是要替代下面这些 framework，而是把它们纳入更 ### Runtime -- 统一 `workspace/` 镜像 -- adapter 驱动执行 +- 统一 `workspace/` 镜像；生产环境采用 thin AMI（us-east-2） +- adapter 驱动执行，覆盖 **8 个 runtime**（Claude Code、Hermes、Gemini CLI、LangGraph、DeepAgents、CrewAI、AutoGen、OpenClaw） - Agent Card 注册 -- awareness-backed memory +- awareness-backed memory；**Memory v2 由 pgvector 支撑**语义召回 - plugin 挂载共享 rules/skills - 本地 skills 热加载 - coordinator-only delegation 路径 @@ -220,6 +224,21 @@ Molecule AI 并不是要替代下面这些 framework，而是把它们纳入更 - runtime tiers - 终端与文件层面的 workspace 直接排障 +### SaaS（由 [`molecule-controlplane`](https://github.com/Molecule-AI/molecule-controlplane) 提供） + +- 多租户运行在 AWS EC2 + Neon（每租户一个 Postgres branch）+ Cloudflare Tunnels（每租户一条隧道，对外不开任何端口） +- WorkOS AuthKit + Stripe Checkout + Customer Portal +- AWS KMS 信封加密（DB / Redis 连接串）；AWS Secrets Manager 负责租户 bootstrap +- `tenant_resources` 审计表 + 30 分钟 boot-event-aware reconciler —— 每个 CF / AWS lifecycle 事件都有记录，每 30 分钟比对 claim 与实际状态 + +### 在 Claude Code 里直接接入（由 [`molecule-mcp-claude-channel`](https://github.com/Molecule-AI/molecule-mcp-claude-channel) 提供） + +- 把 Molecule A2A 流量桥接到本地 Claude Code 会话的 MCP 插件 +- 订阅一个或多个 workspace；peer 的消息会以 user-turn 出现，回复会经 Molecule A2A 路由出去 +- 无需公网隧道、无需公开端点 —— 插件启动时自动把每个 watched workspace 注册成 `delivery_mode=poll`，长轮询 `/activity?since_id=…` +- 多租户友好：单次安装即可同时 watch 跨多个 Molecule 租户的 workspace（`MOLECULE_PLATFORM_URLS` 按 workspace 配置） +- 通过标准 marketplace 流程安装：`/plugin marketplace add Molecule-AI/molecule-mcp-claude-channel` → `/plugin install molecule-channel@molecule-mcp-claude-channel` + ## 适合什么团队 Molecule AI 特别适合下面这些场景： @@ -232,17 +251,23 @@ Molecule AI 特别适合下面这些场景： ## 架构总览 ```text -Canvas (Next.js :3000) <--HTTP / WS--> Platform (Go :8080) <---> Postgres + Redis - | | - | +--> Docker provisioner / bundles / templates / secrets +Canvas (Next.js 15, warm-paper :3000) <--HTTP / WS--> Platform (Go 1.25 :8080) <---> Postgres + Redis + | | + | +--> Provisioner: Docker (本地) / EC2 + SSM (生产) + | +--> bundles · templates · secrets · KMS | - +-------------------- 展示 --------------------> workspaces, teams, tasks, traces, events + +------------------------- 展示 ------------------------> workspaces, teams, tasks, traces, events -Workspace Runtime (Python image with adapters) - - LangGraph / DeepAgents / Claude Code / CrewAI / AutoGen / OpenClaw - - Agent Card + A2A server - - heartbeat + activity + awareness-backed memory +Workspace Runtime (Python ≥3.11，含 adapter 集合的镜像) + - 8 个 adapter: LangGraph / DeepAgents / Claude Code / CrewAI / AutoGen / Hermes / Gemini CLI / OpenClaw + - Agent Card + A2A server（typed-SSOT 响应路径，RFC #2967） + - heartbeat + activity + awareness-backed memory（Memory v2 —— pgvector 语义召回） - skills + plugins + hot reload + +SaaS Control Plane (molecule-controlplane，私有) + - 每租户 EC2 + Neon (Postgres branch) + Cloudflare Tunnel + - WorkOS · Stripe · KMS · AWS Secrets Manager + - tenant_resources 审计 + 30 分钟 reconciler ``` ## 快速开始 @@ -296,7 +321,11 @@ npm run dev ## 当前范围说明 -当前 `main` 已经包含核心平台、Canvas、memory model、6 个正式 adapter、skill lifecycle 和主要运维面。像 **NemoClaw** 这样的相邻 runtime 路线仍然属于分支级工作，只有合并后才会进入正式支持列表，这里会明确区分。 +当前 `main` 已经包含核心平台、Canvas v4（warm-paper 主题）、Memory v2（pgvector 语义召回）、typed-SSOT A2A 响应路径（RFC #2967）、**8 个正式 adapter**（Claude Code、Hermes、Gemini CLI、LangGraph、DeepAgents、CrewAI、AutoGen、OpenClaw）、skill lifecycle，以及主要运维面。 + +配套的私有仓库 [`molecule-controlplane`](https://github.com/Molecule-AI/molecule-controlplane) 提供 SaaS 层 —— 多租户编排（EC2 + Neon + Cloudflare Tunnels）、KMS 信封加密、WorkOS 鉴权、Stripe 计费，以及 `tenant_resources` 审计表加 30 分钟 reconciler。 + +像 **NemoClaw** 这样的相邻 runtime 路线仍然属于分支级工作，只有合并后才会进入正式支持列表，这里会明确区分。 ## License diff --git a/docs/assets/branding/molecule-icon.svg b/docs/assets/branding/molecule-icon.svg new file mode 100644 index 00000000..b6a7814c --- /dev/null +++ b/docs/assets/branding/molecule-icon.svg @@ -0,0 +1,28 @@ + + + + + + + + + + + + + + + + + + + diff --git a/docs/assets/branding/molecule-logo.svg b/docs/assets/branding/molecule-logo.svg new file mode 100644 index 00000000..839c5aa1 --- /dev/null +++ b/docs/assets/branding/molecule-logo.svg @@ -0,0 +1,17 @@ + + + + + + + + + + + + + + + + +