melchizedek

status: active · source

Melchizedek is a headless Node.js CLI for running hierarchical agent graphs, called Syndicates, built on the Google Agent Development Kit. It’s the reference implementation for many of the orchestration ideas discussed in the posts: delegation, critic loops, hierarchical task decomposition, and long-term memory.

what it does

Doctrine-driven agents: every syndicate member is governed by written law as much as by a persona, carrying communication laws, a memory doctrine, safety boundaries, and research rules. The Patient Advocate cites the provenance of every remembered fact; the image pipeline’s inventory agent is structurally blind to expectations. Behavior is designed, then enforced.
Memory that evolves: session transcripts distill into structured records (date, source, exact units, status, index keys); corrections supersede old records, which stay as linked history; recall runs on similarity, index keys, and dates together. Ingestion is incremental and deduplicated by meaning, so restatements are dropped at the door while every doubt resolves toward storing, and each syndicate can declare its own domain rules for what the distiller keeps.
Two orchestration methods: delegation (the default), where sub-agents are tools on the orchestrator and it composes the reply; and plan-dispatch, where a tool-less classifier names one route, code runs that specialist directly, and the specialist’s own output is the answer, with no relay turn, and every routing failure resolves to a declared default route that still answers.
Multi-model teams, any provider: the model: line in an agent’s YAML is the whole routing decision. gemini-* ids run on Google, claude-* on Anthropic, gpt-* on OpenAI, grok-* on xAI, and ollama/* on your own machine with no key at all. Each agent in a syndicate picks its provider independently, so one team can mix a local Qwen researcher with a Claude orchestrator. The framework registers whichever providers your keys unlock and routes by the model id.
Provider-agnostic web search: declare the web_search tool and each agent uses its own model’s native search: Gemini grounding, Anthropic’s search server tool, OpenAI’s Responses search, xAI’s agent tools. Local models, which have none, run without it and say so in the logs.
Deterministic page reading: search is server-side, so the provider picks the pages and the snippets. The web_extract tool is its complement, fetching the URLs the agent chooses and returning the clean page text, unsummarized, under a fixed character budget with resumable paging. Keyless, so it is the one web capability local models get too.
A2A service mode: any syndicate can be served as a stateless JSON-RPC agent-to-agent endpoint over HTTP, with bring-your-own-key routing so inference costs land on the caller.
A knowledge bundle with a gardener: the repo documents itself as a bundle of linked markdown concepts (Open Knowledge Format) whose links form a knowledge graph. Scripts build the structural pages from the YAML/SQL truth, a model fills the prose once, and agents navigate, query, and revise it through a validated save gate, and the whole bundle serves to any MCP client. The worked story: The company brain.
One readable file per team: the whole hierarchy (models, prompts, tools, delegation rules) declares itself in a single YAML document you can diff and teach from.
Distributed as an npm package: the engine installs as melchizedek-agents, typed and versioned, so your syndicates live in your repository: loadSyndicate reads your own config/agents/, the starter pack (every syndicate the curriculum teaches) ships inside the package to copy from, and two CLIs come with it: npx melchizedek-chat for conversation and npx melchizedek-serve for the A2A endpoint. Cloning the repo remains the course path; the package is where your agents go to live afterward.

why it matters for this curriculum

Most agent frameworks hide the orchestration inside code. Melchizedek makes the shape of a multi-agent system a readable artifact: you can diff two syndicates the way you diff two configs. For teaching, that’s the point: the architecture of delegation is on the page, not buried in a call stack.

Posts that use melchizedek as their worked example will link here, and this page will grow into the framework’s public home, with walkthroughs, example syndicates, and eventually live demos served from its A2A mode.

example syndicates

Syndicate	Pattern it demonstrates
Global Synthesis Council	parallel research + synthesis
Delegation router	routing work to specialist subagents
Critic workflow	structured review loops
The Scriptorium	agents tending a knowledge bundle through a validated gate
Hierarchical decomposition	breaking goals into subtasks
Financial Council	multi-analyst report generation
Style Council	voice as engineered communication laws
Image Production	spec-first generation + blind inventory / spec audit
Augustin	multi-agent, multi-modal fact-checking: X sweep + web verification under a tool-free arbiter

Each pattern above is taught hands-on in the curriculum, with the syndicate’s verbatim YAML as a download.

bring your own keys

Melchizedek runs on whichever provider accounts you already have. Every key is optional; each one unlocks exactly the model ids that belong to it, and nothing else asks for it. A syndicate whose every agent is an ollama/* model needs no key at all, because the framework checks the loaded graph and demands only what it declares. What each key costs, honestly:

Key	Unlocks	Cost
none (local Ollama)	every `ollama/*` agent — open-weight models like Qwen 3, running on your machine, nothing leaving it	free — install Ollama and pull a model
`GOOGLE_GENAI_API_KEY`	`gemini-*` agents, Gemini search grounding, image generation, and the embedding model behind long-term memory	free at aistudio.google.com; the free tier covers every Gemini text syndicate AND the memory embeddings. The image-generation model alone is paid-tier only, and heavy search grounding draws paid quota
`ANTHROPIC_API_KEY`	`claude-*` agents	paid — usage-billed, no free tier
`OPENAI_API_KEY`	`gpt-*` agents (GPT-5 family, o-series)	paid — usage-billed at platform.openai.com
`XAI_API_KEY`	`grok-*` agents	paid — usage-billed at console.x.ai
Supabase `URL` + `service_role` key	optional — persistent sessions and long-term memory (Knowledge Keeper, Patient Advocate)	free — the free project tier is plenty; run the schema + hardening SQL from the repo docs
`A2A_SERVER_SECRET`	serving any syndicate as an authenticated A2A endpoint	free — not a vendor key; you generate it yourself (`openssl rand -hex 32`)

To see the whole surface at once, run npm run demo:models in the repo: it sends one prompt to a lightweight agent of every provider you have a key for (plus the local model), prints each model’s answer and its thinking where the model exposes one, and traces the tokens and latency of every request. Providers you haven’t configured are skipped with the reason, so the demo runs on any machine, keys or none.

The private financial syndicates (the Financial Council pattern) add market-data keys on top: price and fundamentals data comes from Yahoo Finance without a key, but technical indicators come from TAAPI, a paid subscription: without it the indicator tool falls back to slower, manually computed values from Yahoo history and labels them as such. Running the financial stack fully means paying for TAAPI; everything the public repo and the curriculum teach runs without it.

Set it up with your coding agent: melchizedek-agent-setup.md is a paste-ready prompt that has your coding agent do the machine steps, the steps that stay yours (keys, database), how to begin testing the agents, and the follow-up prompts for wiring a syndicate into your own app. The same file ships in the repo as AGENT_SETUP.md.

Source code and full documentation live in the public repository: github.com/jhwadman/melchizedek-agents, which holds every syndicate the curriculum teaches, the structured-memory pipeline, the A2A server, and the database schema, with quickstart and deployment docs. (The Financial Council pattern remains private; the repository ships the teaching syndicates.)