forked from molecule-ai/molecule-core
a33c879017
Closes #3026. Final piece of RFC #2945. ## What's new New package internal/messagestore/ holds: - MessageStore interface — single read-side contract operators implement to plug in alternative chat-history backends. - ChatMessage / ChatAttachment / ListOptions types — canonical data shapes returned by any impl, mirrors canvas's TS ChatMessage. - PostgresMessageStore — platform-default impl wrapping the activity_logs query + A2A-envelope parser ported in PR-C. Behavior is byte-identical to the pre-PR-D handler. ## What moves The activity_logs query, the parser (activityRowToChatMessages, extractRequestText, extractChatResponseText, extractFilesFromTask, etc.), and the internal-self-message predicate all migrate from internal/handlers/chat_history.go into the new package. handlers/ chat_history.go becomes a thin HTTP-shape adapter: parse query params → store.List(ctx, workspaceID, opts) → emit JSON Compile-time interface assertion in postgres_store.go catches future drift if the interface evolves and the impl falls behind. ## Why this PR OSS operators wanting to: - Tier hot/warm/cold storage (recent in Postgres, archival in S3) - Use a vector store with hybrid search (Pinecone, Weaviate) - Run an in-memory store for ephemeral test environments - Federate history across regions …had no extension point — they'd have to fork the handler. This PR makes that a constructor swap at router.go. ## Tests Parser-level (22 tests, MOVED to internal/messagestore/postgres_ store_test.go): every TS test case in canvas/src/components/tabs/chat/__tests__/historyHydration.test.ts has a Go counterpart. Timestamp preservation, user/agent extraction, internal-self filter, role decision (status=error vs agent-error prefix), v0/v1 file shapes, malformed JSON resilience. Handler-level (9 NEW tests in internal/handlers/chat_history_test.go): thin adapter coverage using a fake MessageStore. UUID validation, before_ts RFC3339 validation, default limit, max-limit clamp, invalid-limit fallback, before_ts passthrough, empty-array (not null) JSON shape, attachment shape preservation, store-error → 502 mapping. Compile-time interface conformance: PostgresMessageStore satisfies MessageStore, fakeStore (test fake) satisfies MessageStore. Mutation-tested. Removed UUID validation in the handler; confirmed TestChatHistoryHandler_RejectsNonUUIDWorkspaceID fires red (status 200 instead of 400, non-UUID reaches the store). Restored, all green. Full handlers + messagestore + router test runs green; full repo go test ./... green. ## SSOT decision ChatMessage / ChatAttachment / parser / DB query all live in internal/messagestore/ ONLY. handlers/chat_history.go imports the package and uses the types via messagestore.ChatMessage etc. — no re-declaration anywhere. ## Three weakest spots (hostile-reviewer self-pass) 1. The internal-self prefix list (Delegation results are ready...) is a package var in messagestore/postgres_store.go. A future impl that wants to override the predicate must reach into the package to use IsInternalSelfMessage or define its own. Acceptable: the predicate is part of the contract; if an impl wants different semantics it owns that decision explicitly. 2. ListOptions has Limit + BeforeTS + HasBefore; future paging needs (after_ts, peer_id filter, role filter) require additive struct field additions, which is a soft API break for any impl that handles ListOptions positionally. Mitigated by Go's struct-literal convention (named fields by default); also flagged in the interface comment for impl authors. 3. The handler does NOT log when a store returns an error — it just maps to 502. An impl that wants to surface its error class up the stack can't, today. If/when an impl needs that, the interface can add a typed-error contract in a follow-up. Today's coverage is sufficient: most ops issues land in the store impl's own logs. ## Security review - Untrusted input? Same as PR-C — agent-emitted JSON parsed defensively. New fakeStore in tests can't reach production. - Trust boundary? Same. Interface lives BEHIND wsAuth; impls only see workspace IDs already authenticated. - Auth/authz? Inherited from handler; the interface doesn't authenticate. - PII / secrets in logs? Documented in the interface contract: impls MUST NOT log full message bodies / attachment URIs. The Postgres impl logs nothing on the happy path. - Output sanitization? Same plain-text + opaque-URI surface as PR-C. Canvas validates attachment-URI schemes. No security-relevant changes beyond what /chat-history already exposes via PR-C. Considered, not skipped. ## Versioning / backwards compat - New internal package. Zero public API change. - Single caller site in router.go updated (one-line constructor change). NewChatHistoryHandler() → NewChatHistoryHandler(store). - No schema change, no migration. - Existing /chat-history endpoint unchanged on the wire — clients don't notice the refactor. ## Phasing This is the final RFC #2945 piece. Follow-ups parked: - PR-C-2 (canvas migration): swap canvas loadMessagesFromDB to call /chat-history instead of /activity. Independent of this PR; blocked only by canvas team's calendar. - Sample alternative impls (S3, in-memory) for OSS docs: separate PR when the first OSS consumer materializes; demonstration code untested against a real workload is anti-pattern. 🤖 Generated with [Claude Code](https://claude.com/claude-code) |
||
|---|---|---|
| .ci-trigger | ||
| .githooks | ||
| .github | ||
| canvas | ||
| docs | ||
| infra | ||
| scripts | ||
| tests | ||
| tools | ||
| workspace | ||
| workspace-server | ||
| .coverage-allowlist.txt | ||
| .env.example | ||
| .gitattributes | ||
| .gitignore | ||
| .mcp.json.example | ||
| CODE_OF_CONDUCT.md | ||
| CONTRIBUTING.md | ||
| COVERAGE_FLOOR.md | ||
| docker-compose.infra.yml | ||
| docker-compose.yml | ||
| LICENSE | ||
| manifest.json | ||
| railway.toml | ||
| README.md | ||
| README.zh-CN.md | ||
| render.yaml | ||
The Org-Native Control Plane For Heterogeneous AI Agent Teams
The world's most powerful governance platform for AI agent teams.
Visual Canvas • Runtime Compatibility • Hierarchical Memory • Skill Evolution • Operational Guardrails
Docs Home • Quick Start • Architecture • Platform API • Workspace Runtime
The Pitch
Molecule AI is the most powerful way to govern an AI agent organization in production.
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 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.
Very few teams can run all of that as a governed organization with clear structure, durable memory boundaries, and production operations.
That is the gap Molecule AI closes.
Why Molecule AI Feels Different
1. The node is a role, not a task
In Molecule AI, a workspace is an organizational role. That role can begin as one agent, later expand into a sub-team, and still keep the same external identity, hierarchy position, memory boundary, and A2A interface.
2. The org chart is the topology
You do not wire collaboration paths by hand. Hierarchy defines the default communication surface. The structure is not decorative UI. It is part of the operating model.
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.
4. Memory is treated like infrastructure
Molecule AI's HMA approach is designed around organizational boundaries, not just “store more context somewhere.” Durable recall, scoped sharing, awareness namespaces, and skill promotion are all part of one coherent system.
5. It comes with a real control plane
Registry, heartbeats, restart, pause/resume, activity logs, approvals, terminal access, files, traces, bundles, templates, and WebSocket fanout are not afterthoughts. They are first-class parts of the platform.
The Category Gap Molecule AI Fills
| Category | What it does well | Where it breaks | What Molecule AI adds |
|---|---|---|---|
| Workflow builders | Visual task automation | Nodes are tasks, not durable organizational roles | Role-native workspaces, hierarchy, long-lived teams |
| Agent frameworks | Strong runtime semantics | Weak control plane and weak org-level operations | Unified lifecycle, canvas, registry, policies, observability |
| Coding agents | Excellent local execution | Usually not designed as team infrastructure | Workspace abstraction, A2A collaboration, platform ops |
| Custom multi-agent graphs | Full flexibility | Brittle topology and governance sprawl | Standardized operating model without losing runtime freedom |
What Makes Molecule AI Defensible
| Advantage | Why it matters in practice |
|---|---|
| Role-native workspace abstraction | Your org structure survives model swaps, framework changes, and team expansion |
| Fractal team expansion | A single specialist can become a managed department without breaking upstream integrations |
| Heterogeneous runtime compatibility | Different teams can keep their preferred agent architecture while sharing one control plane |
| HMA + awareness namespaces | Memory sharing follows hierarchy instead of leaking across the whole system |
| Skill evolution loop | Durable successful workflows can graduate from memory into reusable, hot-reloadable skills |
| WebSocket-first operational UX | The canvas reflects task state, structure changes, and A2A responses in near real time |
| Global secrets with local override | Centralize provider access, then override only where a workspace needs specialized credentials |
Runtime Compatibility, Compared
Molecule AI is not trying to replace the frameworks below. It is the system that makes them easier to run together.
| Runtime / architecture | Status in current repo | Native strength | What Molecule AI adds |
|---|---|---|---|
| LangGraph | Shipping on main |
Graph control, tool use, Python extensibility | Canvas orchestration, hierarchy routing, A2A, memory scopes, operational lifecycle |
| DeepAgents | Shipping on main |
Deeper planning and decomposition | Same workspace contract, team topology, activity stream, restart behavior |
| 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 |
| 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 |
This is the key idea: many agent runtimes, one organizational operating system.
Why The Memory Architecture Compounds
Most projects stop at “we added memory.” Molecule AI pushes further:
| Conventional memory setup | Molecule AI |
|---|---|
| Flat store or weak namespaces | Hierarchy-aligned LOCAL, TEAM, GLOBAL scopes |
| Sharing is easy to overexpose | Sharing is explicit and structure-aware |
| Memory and procedure get mixed together | Memory stores durable facts; skills store repeatable procedure |
| Every agent can become over-privileged | Workspace awareness namespaces reduce blast radius |
| UI memory and runtime memory blur together | Separate surfaces for scoped agent memory, key/value workspace memory, and recall |
The flywheel
Task execution
-> durable insight captured in memory
-> repeated success becomes a signal
-> workflow promoted into a reusable skill
-> skill hot-reloads into the runtime
-> future work gets faster and more reliable
This is one of Molecule AI's strongest long-term advantages: the system can get more operationally capable without turning into one giant hidden prompt.
Self-Improving Agent Teams, Built Into Molecule AI
Most agent systems stop at "a smart runtime." Molecule AI pushes further: it gives teams a way to capture what worked, promote repeatable procedure into skills, reload those improvements into live workspaces, and keep the whole loop visible at the platform level.
| Positioning lens | Conventional self-improving agent pattern | Molecule AI |
|---|---|---|
| Unit of improvement | A single agent session or runtime | A workspace, a team, and eventually the whole org graph |
| Operational surface | Mostly hidden inside the agent loop | Visible in the platform, Canvas, activity stream, memory surfaces, and runtime controls |
| Strategic outcome | A smarter agent | A compounding organization with durable knowledge and governed reusable skills |
Where that shows up in Molecule AI
| Core mechanism | Molecule AI module(s) | Why it matters |
|---|---|---|
| Durable memory that survives sessions | workspace/builtin_tools/memory.py, workspace/builtin_tools/awareness_client.py, workspace-server/internal/handlers/memories.go |
Memory is not just durable, it is workspace-scoped and can route into awareness namespaces tied to the org structure |
| Cross-session recall | workspace-server/internal/handlers/activity.go (/workspaces/:id/session-search) |
Recall spans both activity history and memory rows, so the system can search what happened and what was learned without inventing a separate hidden store |
| Skills built from experience | workspace/builtin_tools/memory.py (_maybe_log_skill_promotion) |
Promotion from memory into a skill candidate is surfaced as an explicit platform activity, not a silent internal side effect |
| Skill improvement during use | workspace/skill_loader/watcher.py, workspace/skill_loader/loader.py, workspace/main.py |
Skills hot-reload into the live runtime, so improvements become available on the next A2A task without restarting the workspace |
| Persistent skill lifecycle | workspace-server/cmd/cli/cmd_agent_skill.go, workspace/plugins.py |
Skills are not just generated once; they can be audited, installed, published, shared, mounted by plugins, and governed as reusable operational assets |
Why this matters in Molecule AI
-
The learning loop is org-aware, not just session-aware. Memory can live at
LOCAL,TEAM, orGLOBALscope, and awareness namespaces give each workspace a durable identity boundary. -
The learning loop is visible to operators. Promotion events, activity logs, current-task updates, traces, and WebSocket fanout mean self-improvement is part of the control plane, not a hidden black box.
-
The learning loop compounds across teams, not just one agent. A workflow learned by one workspace can become a governed skill, reload into the runtime, appear in the Agent Card, and become usable inside a larger organizational hierarchy.
The result is not just “an agent that learns.” It is an organization that gets more capable as its workspaces accumulate durable memory and reusable procedure.
What Ships In main
Canvas
- Next.js 15 + React Flow + Zustand
- drag-to-nest team building
- empty-state deployment + onboarding wizard
- template palette
- bundle import/export
- 10-tab side panel for chat, activity, details, skills, terminal, config, files, memory, traces, and events
Platform
- Go/Gin control plane
- workspace CRUD and provisioning
- registry and heartbeats
- browser-safe A2A proxy
- team expansion/collapse
- activity logs and approvals
- secrets and global secrets
- files API, terminal, bundles, templates, viewport persistence
Runtime
- unified
workspace/image - adapter-driven execution
- Agent Card registration
- awareness-backed memory integration
- plugin-mounted shared rules/skills
- hot-reloadable local skills
- coordinator-only delegation path
Ops
- Langfuse traces
- current-task reporting
- pause/resume/restart flows
- activity streaming
- runtime tiers
- direct workspace inspection through terminal and files
Built For Teams That Need More Than A Demo
Molecule AI is especially strong when you need to run:
- AI engineering teams with PM / Dev Lead / QA / Research / Ops roles
- mixed runtime organizations where one team prefers LangGraph and another prefers Claude Code
- long-lived agent organizations that need memory boundaries and reusable procedures
- internal platforms that want to expose agent teams as structured infrastructure, not ad hoc scripts
Architecture
Canvas (Next.js :3000) <--HTTP / WS--> Platform (Go :8080) <---> Postgres + Redis
| |
| +--> Docker provisioner / bundles / templates / secrets
|
+-------------------- 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
- skills + plugins + hot reload
Quick Start
git clone https://github.com/Molecule-AI/molecule-monorepo.git
cd molecule-monorepo
cp .env.example .env
# Defaults boot the stack locally out of the box. See .env.example for
# production hardening knobs (ADMIN_TOKEN, SECRETS_ENCRYPTION_KEY, etc.).
./infra/scripts/setup.sh
# Boots Postgres (:5432), Redis (:6379), Langfuse (:3001),
# and Temporal (:7233 gRPC, :8233 UI) on the shared
# `molecule-monorepo-net` Docker network. Temporal runs with
# no auth on localhost — dev-only; production must gate it.
#
# Also populates the template/plugin registry by cloning every repo
# listed in manifest.json into workspace-configs-templates/,
# org-templates/, and plugins/. Requires jq — install via
# `brew install jq` (macOS) or `apt install jq` (Debian). Idempotent:
# re-runs skip any target dir that's already populated.
cd workspace-server
go run ./cmd/server # applies pending migrations on first boot
cd ../canvas
npm install
npm run dev
Then open http://localhost:3000:
- Deploy a template or create a blank workspace from the empty state.
- Follow the onboarding guide into
Config. - Add a provider key in
Secrets & API Keys. - Open
Chatand send the first task.
Documentation Map
- Docs Home
- Quick Start
- Product Overview
- System Architecture
- Memory Architecture
- Platform API
- Workspace Runtime
- Canvas UI
- Local Development
- Backend Parity Matrix — Docker vs EC2 feature parity tracker
- Testing Strategy — tiered coverage floors, not blanket 100%
- PR Hygiene — small PRs, clean branches, cherry-pick on drift
- Engineering Postmortems — architecture + testing lessons from real incidents
- Ecosystem Watch — adjacent projects we track (Holaboss, Hermes, gstack, …)
- Glossary — how we use "harness", "workspace", "plugin", "flow" vs. ecosystem neighbors
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.
License
Business Source License 1.1 — copyright © 2025 Molecule AI.
Personal, internal, and non-commercial use is permitted without restriction. You may not use the Licensed Work to offer a competing product or service. On January 1, 2029, the license converts to Apache 2.0.