75dee70027
CI fully green (all 6 checks pass). Docs-only: adds docs/glossary.md, links from README.md and CLAUDE.md. Closes #320.
49 lines
4.8 KiB
Markdown
49 lines
4.8 KiB
Markdown
# Glossary — Molecule AI terminology vs. ecosystem neighbors
|
|
|
|
The agent-infra ecosystem has coalesced around a common vocabulary that
|
|
nevertheless means different things in different projects. This page
|
|
defines how Molecule AI uses each term and flags the conflicts you're
|
|
most likely to hit when reading adjacent documentation.
|
|
|
|
Cross-referenced from
|
|
[`docs/ecosystem-watch.md`](./ecosystem-watch.md) — when a new project
|
|
lands in the watch list with a colliding term, add a row here.
|
|
|
|
## Core terms
|
|
|
|
| Term | What we mean | What others mean |
|
|
|------|--------------|------------------|
|
|
| **harness** | The Claude Code execution environment: `~/.claude/settings.json`, hooks, skills, MCP servers, the surrounding CLI. The layer *around* the agent that enforces behavior before tool calls fire. | **OpenHarness** (`HKUDS/OpenHarness`): a research framework wrapper for studying agent internals — closer to a probe than an enforcement layer. |
|
|
| **workspace** | An isolated Docker container running one agent with a role, git state, hook pipeline, runtime image, and per-workspace bearer token. Long-lived — a workspace is provisioned once and stays up. | **Paperclip**: closer to "employee" (a persona with memory). **Hermes**: closer to "project" (a unit of work scoped by time). In Molecule, persona = role, unit of work = task/delegation. |
|
|
| **plugin** | A directory under `plugins/` packaging one or more skills or an MCP server wrapper, installable per-workspace via `POST /workspaces/:id/plugins`. Governed by `plugin.yaml`. | **Langflow**: a visual UI node / component in a flowchart. **CrewAI**: a Python-importable callable registered as a capability. |
|
|
| **agent** | A persistent containerized workspace running continuously — an identity with memory, a role, and a schedule. Not a one-shot invocation. | Most frameworks (AutoGPT, LangChain agents, OpenAI Assistants): a stateless function-call loop. No persistence between invocations unless explicitly checkpointed. |
|
|
| **flow** | A task execution within a workspace — a request enters, the agent runs tools, emits a response, logs activity. No explicit graph abstraction. | **Langflow**: a directed graph of nodes you author visually. **LangGraph**: a stateful graph of callable nodes. Our "flow" is an imperative timeline, not a graph. |
|
|
| **team** | A named cluster of workspaces under a PM (org template `expand_team`). Used for role grouping in Canvas. | **CrewAI**: a "crew" is a sequence of agents that pass a task through a declared order. Our "team" is an org-chart abstraction, not an execution order. |
|
|
| **skill** | A directory with `SKILL.md` that an agent invokes via the `Skill` tool. Skills are documentation + optional scripts that teach an agent a recipe. | **Anthropic Skills API**: nearly identical. **CrewAI tool**: closer to our plugin's MCP tool, not our skill. |
|
|
| **channel** | An outbound/inbound social integration (Telegram, Slack, …) per-workspace, wired in `workspace_channels`. | Slack's "channel": the container for messages. We use "channel" for the adapter + credentials, not the conversation itself. |
|
|
| **runtime** | The execution engine image tag for a workspace: one of `langgraph`, `claude-code`, `openclaw`, `crewai`, `autogen`, `deepagents`, `hermes`. | **LangGraph runtime**: the Python process running the graph. We use "runtime" for the Docker image + adapter pairing, not the inner process. |
|
|
|
|
## Near-miss terms
|
|
|
|
These don't appear in the table above because we don't use them in the
|
|
same sense as the reference project — flagged so you don't confuse the
|
|
two:
|
|
|
|
- **crew** (CrewAI) — we don't use this term; the analogue is **team**.
|
|
- **tool** — a LangChain `@tool`-decorated callable, shared vocabulary with most frameworks. No conflict, but "skill" is the user-facing abstraction an agent picks up from `SKILL.md`; "tool" is the thing under the hood.
|
|
- **component** (Langflow) — no analogue. We have **plugin** (role-level), **skill** (agent-recipe-level), and **adapter** (runtime-level). A Langflow "component" is visual; ours is structural.
|
|
- **pipeline** — overloaded in our repo: CI pipeline, ingestion pipeline, etc. Always use the qualifier.
|
|
|
|
## When to update this file
|
|
|
|
- A project enters `docs/ecosystem-watch.md` with a term that collides with ours → add a row.
|
|
- We rename an internal term (e.g., "workspace" to "agent") → update **every** row that references it, update `CLAUDE.md`, update `README.md`, update `docs/architecture.md`.
|
|
- A user reports confusion reading a cross-project tutorial → add a row with the confusing term.
|
|
|
|
## Cross-references
|
|
|
|
- [`README.md`](../README.md) — top-level stack description.
|
|
- [`CLAUDE.md`](../CLAUDE.md) — operational vocabulary for agents in this repo.
|
|
- [`docs/ecosystem-watch.md`](./ecosystem-watch.md) — source of truth for adjacent-project claims.
|
|
- [`docs/architecture.md`](./architecture.md) — deeper definitions for workspace, canvas, platform.
|