▢→AgentMarkv0.2.0
Your AI stack changes every week. Your architecture docs don't.

Document AI systems that tell you when they're wrong.

A text notation for AI architecture: sketch the topology, record the assumptions behind it, and let the linter flag the diagram the moment one expires.

Try it now — no signup Read the spec
Runs in your browser One plain-text file Open spec · v0.2.0
hero.agentmark
[human#you: You] -> [agent#a: Agent] -> [model#m: Model]
[agent#a] -> [mcp#g: MCP Gateway] -> [tool#t: Tool]
[agent#a] -> [rag#r: RAG] -> [data#d: Data]
[eval#e: Eval] ~> [agent#a]
You HUMAN Eval EVAL Agent AGENT Model MODEL MCP Gateway MCP RAG RAG Tool TOOL Data DATA

Five arrows. That's the syntax.

Nodes are [type#id: Label]. Edges are one of five arrows. You already know it.

->
[A] -> [B]

uses / calls / sends to

=>
[A] => [B]

hands off / escalates to

x>
[A] x> [B]

blocks / forbids

~>
[A] ~> [B]

observes / subscribes to

<->
[A] <-> [B]

interacts with (two-way)

It catches decay you'd never see in a diagram.

This refund decision's review date has passed. The linter says so — in your editor and in CI.

support.agentmark
agentmark: 0.2
title: Support Triage
as_of: 2026-06-01
---
[human#u: Customer] <-> [agent#triage: Triage Agent]
[agent#triage] => [agent#refund: Refund Agent]
[agent#triage] -> [model#m: Claude Opus]
[agent#refund] x> [tool#pay: Payments API]

decision D-1: "Route refunds through a human gate" {
  because: [C-1]  review_by: 2026-05-01   ⚠ overdue
}
claim C-1: "Refund false-positives cost > review time" {
  confidence: 0.6
  evidence: ledger-q1
  as_of: 2026-02-01
}
Customer HUMAN Triage Agent AGENT Refund Agent AGENT Claude Opus MODEL Payments API TOOL

Stale: decision D-1 — its review_by passed and claim C-1's evidence is four months old.

Open this in the editor

One file. Every view.

The same .agentmark source, projected three ways. No second copy to keep in sync.

view: topologywhat connects to what
Hermes Coding Harness traces Joel HUMAN Browser Agent AGENT Hermes HARNESS Coding Agent AGENT MCP Tool Selector MIDDLEWARE MCP Gateway MCP Codex MODEL Test Runner TOOL Repository FS OpenTelemetry Traces LOG
view: decisionwhy it's shaped this way
Hermes Coding Harness supported by supported by constrained by constrained by Coding Harnesses LANDSCAPE D-001 · Use Codex as primary … DECISION K-001 · Claude Code backend h… CONSTRAINT K-002 · Prefer cost-optimized… CONSTRAINT C-001 · Codex is currently be… CLAIM C-003 · GLM is cheapest among… CLAIM
view: risktrust, authority, blast radius
Hermes Coding Harness Browser Sandbox SANDBOX K-001 · Claude Code backend h… CONSTRAINT K-002 · Prefer cost-optimized… CONSTRAINT
Open the full example

A diagram answers one question. AgentMark answers seven.

  1. 1What connects to what?
  2. 2Why was it chosen?
  3. 3Under what assumptions?
  4. 4What constraints apply?
  5. 5What evidence supports this?
  6. 6When does it expire?
  7. 7How do we know it still works?

Five arrows

No syntax to learn. Pastes straight into Notion and Slack.

One file, many views

Topology, decision, risk — each a generated diagram, always in sync.

A knowledge layer

Claims, constraints and decisions, with confidence and evidence.

Assumptions expire

Every dated statement carries as_of / review_by; the linter catches the lapse.

Cross-language core

One canonical parser + linter + renderer (TS now; Python/Go/C planned).

Lives in your repo

Plain text. Diff it in PRs, run am lint in CI. No SaaS, no database.

Start from a working example

Open any of these in the editor — one click, no setup.

You HUMAN Eval EVAL Agent AGENT Model MODEL MCP Gateway MCP RAG RAG Tool TOOL Data DATA

Sketch (viral core)

Zero setup — every layer gets its own shape.

RAG Pipeline User HUMAN Chat History MEMORY Groundedness Eval EVAL RAG Agent AGENT Embedder EMBED Answer Model MODEL Vector Index INDEX Document Corpus DATA

RAG pipeline

Embed → vector index → corpus, grounding the model.

Multi-Agent Orchestration research draft review reviews User HUMAN Orchestrator AGENT Researcher AGENT Critic AGENT Writer AGENT Web Search TOOL Draft Model MODEL

Multi-agent handoff

An orchestrator hands work off (=>) to specialists.

Hermes over Telegram Telegram Telegram traces Me HUMAN Telegram MCP MCP Hermes HARNESS Worker Agent AGENT Model MODEL OpenTelemetry LOG

Channel (Telegram)

Two-way user↔harness interaction over a chat channel.

Grouped & aligned Cognition Backend Models Tools Me HUMAN Hermes HARNESS Planner AGENT Coder AGENT Sonnet MODEL Haiku MODEL GitHub MCP Slack MCP

Groups & alignment

Cluster, orient and align nodes — with nested subgroups.

Coding Agent (Spec) streams traces forbids You HUMAN No Prod Writes POLICY Codex Harness HARNESS Deploy TOOL Coding Agent AGENT MCP Tool Selector MIDDLEWARE GitHub MCP MCP Claude Sonnet MODEL Test Runner TOOL OpenTelemetry LOG

Spec mode

IDs, roles, properties, fan-out and edge labels.

Browser Agent Governance blocks Browser Agent AGENT No Credential Exfiltration POLICY Playwright DRIVER Chromium BROWSER Browser Sandbox SANDBOX Screenshot FILE

Governance & risk

Trust boundaries, authority, high-risk capabilities.

Observability traces tokens, latency User HUMAN Online Eval EVAL Alerting MONITOR Agent AGENT Model MODEL Tool TOOL OpenTelemetry LOG Token Metrics METRIC

Observability

Telemetry and evals observe (~>) the agent and model.

Hermes Coding Harness traces Joel HUMAN Browser Agent AGENT Hermes HARNESS Playwright DRIVER Coding Agent AGENT MCP Tool Selector MIDDLEWARE MCP Gateway MCP Chromium BROWSER Codex MODEL Test Runner TOOL Repository FS OpenTelemetry Traces LOG Browser Sandbox SANDBOX

Hermes (full)

The complete worked example — topology + knowledge layer.

Make one architecture spec everyone can trust.

1
Draw it

Sketch your topology in the editor.

2
Commit it

Save the .agentmark file. Diff it in PRs.

3
Guard it

Run am lint in CI so stale assumptions fail the build.

Open the editor Star on GitHub