Embercore Glossary
A reference of Embercore-specific terminology. See also the Architecture Decision Records for the reasoning behind these concepts.
Agents
Agent
A specialized AI-powered module that performs a specific role in the marketing workflow. Each agent wraps an LLM provider and exposes domain-specific methods. Embercore has five agents, named after Greek gods (see ADR-004).
Athena
The planner agent. Named after the Greek goddess of wisdom and strategy. Generates structured plan specs from natural-language briefs, validates agent assignments, and detects circular dependencies. Package: agents/athena/.
Hermes
The executor agent. Named after the Greek messenger god. Orchestrates plan execution by running steps in topologically sorted layers, managing checkpoint approvals, and coordinating pause/resume. Package: agents/hermes/.
Apollo
The creative/copy agent. Named after the Greek god of arts and music. Generates marketing copy across content types: blog posts, emails, social media, headlines, ads, landing pages, and newsletters. Package: agents/apollo/.
Hephaestus
The builder/assembler agent. Named after the Greek god of the forge. Assembles final deliverables from agent outputs using builtin templates, LLM-enhanced assembly, or deterministic assembly. Package: agents/hephaestus/.
Hestia
The memory/storage agent. Named after the Greek goddess of the hearth and home. Wraps the SQLite store to provide plan persistence, run tracking, and checkpoint recording. Package: agents/hestia/.
Plans & Workflow
Brief
A natural-language description of a marketing task or campaign provided by the user. Athena converts a brief into a structured plan spec.
Plan
A structured YAML specification describing a multi-step marketing workflow. Contains a name, description, input parameters, and an ordered list of steps. Defined in plan/plan.go as plan.Spec.
Step
A single unit of work within a plan. Each step specifies an agent to execute it, a prompt, optional dependencies on other steps, and whether it requires a checkpoint. Defined as plan.Step.
Topological Sort (TopoSort)
The algorithm (Kahn’s algorithm, plan/toposort.go) used to determine the execution order of plan steps based on their depends_on relationships. Steps with no dependencies execute first; steps in the same “layer” can run in parallel.
Checkpoint
An approval gate within a plan execution. Steps marked checkpoint: true pause execution and present their output for human review before continuing. See ADR-005.
Checkpoint Handler
A callback function (func(step plan.Step, output string) (approved bool, feedback string, err error)) that Hermes invokes at checkpoint steps. Can be an interactive stdin prompt, an MCP request_approval tool call, or a custom handler.
Run
A single execution of a plan. A run tracks its state (pending, running, paused, completed, failed) and the results of each step. Persisted in SQLite via Hestia.
Run State
The current status of a run, including which steps have completed, which are pending, and whether the run is paused at a checkpoint. Retrievable via Hestia.GetRunState().
Artifacts & Output
Artifact
A generated output file or content block produced during a run. Stored in the artifacts table with metadata linking it to its originating run and step.
Variant
One of potentially multiple versions of generated content (e.g., Apollo may produce several headline variants). Defined in agents/apollo/types.go.
Output Type / Output Format
Configuration for Hephaestus specifying what kind of deliverable to assemble (e.g., document, presentation) and in what format. Defined in agents/hephaestus/types.go.
Providers & Configuration
Provider
An interface (internal/provider/provider.go) that abstracts LLM API access. Defines Complete(ctx, messages, opts) and Name(). Implementations exist for Anthropic and OpenAI. See ADR-003.
BYOK (Bring Your Own Key)
Embercore’s authentication model. Users supply their own LLM API keys via environment variables rather than using a bundled key. See ADR-003.
Factory (NewFromEnv)
The function in internal/provider/factory.go that constructs the appropriate provider based on environment variables (EMBERCORE_PROVIDER, ANTHROPIC_API_KEY, OPENAI_API_KEY, etc.).
Base URL
A custom API endpoint for OpenAI-compatible providers. Set via OPENAI_BASE_URL to point to Ollama, LM Studio, Azure OpenAI, or other compatible APIs.
Functional Options
The Go pattern used to configure agents: New(WithProvider(p), WithHestia(h), WithModel(m)). See ADR-008.
Integration & Protocol
MCP (Model Context Protocol)
The integration protocol used by Embercore’s engine. An emerging standard for AI tool communication using JSON-RPC over stdio or HTTP. See ADR-006.
stdio Transport
The default MCP transport mode. The engine binary reads JSON-RPC messages from stdin and writes responses to stdout. Logging goes to stderr.
Tool (MCP Tool)
A named operation registered with the MCP server (e.g., run_workflow, pm_plan, request_approval). External AI assistants invoke these tools to interact with Embercore.
Infrastructure
Monorepo
The repository structure with apps/ (web dashboard), packages/ (engine), and examples/ managed by pnpm workspaces. See ADR-001.
WAL (Write-Ahead Logging)
SQLite journaling mode enabled in internal/store/store.go. Allows concurrent reads and writes, critical for agents recording results while the engine reads state. See ADR-002.
Pure Go SQLite
The modernc.org/sqlite driver — a mechanical translation of SQLite’s C source to Go. Enables CGO_ENABLED=0 builds and easy cross-compilation. See ADR-002.
Context Guard
internal/ctxguard/ — a utility that manages LLM context window limits by dropping optional prompt sections when the context is too large.
Herald
An internal Anthropic client (internal/claude/client.go) used for direct LLM calls with retry/backoff logic. Configurable via HERALD_* environment variables.