Open Source · Agentic AI

Building Agentic Systems

A spec for agentic work, two harnesses that run it, and a memory graph underneath.

Agent harnesses already break projects into steps. They do it privately, in their own shape, and the plan disappears when the session ends. I am building an open alternative in three parts: the Agentic Graph Specification writes the decomposition down as a portable artifact, MagAgent and Loro are harnesses that execute it for developers and for enterprises, and MagGraph gives the agents memory you can read in a text editor.

The throughline

Structure you can review, governance you can prove

Two questions decide whether agentic work is worth trusting with anything that matters: can you see the plan before you pay for it, and can you show what actually happened afterward.

The format

AGS

An open, vendor-neutral document describing the work as a graph of bounded agentic loops, with success criteria the harness checks rather than the model asserts.

The harnesses

MagAgent and Loro

Two programs that read those graphs and run them. One is built for a developer in a terminal, the other for an organization that has to answer to an auditor.

The memory

MagGraph

A graph database where knowledge lives as Markdown files in Git, so what an agent remembers is something a person can read, review, and correct.

All open source AGS and MagAgent are Apache-2.0, MagGraph is MIT or Apache-2.0, Loro is MIT. Everything on this page is public code you can read, fork, or implement against.

01 / Tooling

The Mag Ecosystem

A local-first AI productivity stack: a Rust memory graph, a terminal agent, and a desktop command center. Named for the magpie, a corvid, for the same reasons the birds are studied: memory, tool use, and planning.

What it is

MagGraph is an in-process graph database written in Rust. Knowledge is stored as versioned Markdown nodes inside a Git repository, edges emerge automatically from [[wikilinks]], and Git handles versioning and sync. It ships a Python API, a CLI, and an auto-generated MCP server, plus a lakehouse mode where nodes point at external S3 or Parquet data.

MagAgent is the terminal-native coding and productivity agent that sits on that memory. It connects to 20 provider options across local and cloud models, ships 40 built-in tools and 10 skill libraries, spawns sub-agents for parallel work, saves reusable workflow recipes, loads plugins and MCP servers, and can take tasks from Slack, Discord, or Telegram while you are away from the terminal.

Mag Command Center is the Tauri, React, and TypeScript desktop app over both: project-scoped chats, provider and permission configuration without hand-editing TOML, and a browser for MagGraph memory including backlinks, provenance, and pending candidates. It is packaged for macOS, Windows, and Linux.

How to use it

Install the agent, run the configuration wizard, and work in a project directory. Memory accumulates as you go, and it accumulates as files you can open.

python -m pip install mag-agent
magent configure
magent                       # interactive session in the current project
magent recipe run release-prep
magent graph generate "ship the next API version" --out release.agraph.yaml

MagGraph is useful on its own if you only want the memory layer. Point any agent framework at its MCP server, or import it in Python and query recall bundles, backlinks, and traversals directly.

Why it matters

Most agent memory is an opaque store you cannot inspect and cannot move. Storing it as Markdown in Git means memory is diffable, reviewable in a pull request, correctable by hand, and portable to any tool that reads text. When an agent remembers something wrong about your codebase, you fix a file instead of filing a bug.

02 / Specification

The Agentic Graph Specification

AGS 1.0 is an open, implementation-neutral format for decomposing a project into a graph of agentic loops. It is a draft standard, Apache-2.0 for the code and schemas, CC BY 4.0 for the specification text.

What it is

An Agentic Graph is a directed acyclic graph. Every node is one bounded agentic loop, a unit of work an agent runs end to end. Every edge is a control-flow dependency. A node is not a prompt and not a function call. It carries:

  • A precise brief, written so an agent that has seen nothing else can act on it.
  • Typed inputs and outputs, so data flow is declared separately from control flow.
  • Success criteria the harness evaluates rather than the model asserts. Kinds include command, file_exists, json_schema, regex, expression, llm_judge, and human.
  • An intelligence tier from minimal to frontier, a normalized capability demand that describes the task without naming any model or vendor.
  • Tools, permissions, and budgets, the ceiling on what a node may do and what it may spend.
  • Failure handling: retries with feedback, fallbacks, escalation, and human gates.

Node types cover tasks, decisions, human gates, bounded loops, bounded fan-out maps, and subgraphs. Every loop has a max_iterations and every fan-out has a max_items, so there is no way to write an unbounded document. JSON and YAML are the same data model, and a YAML file that does not survive a lossless round trip through JSON is not a valid AGS document.

How to use it

If you are planning work: author a graph by hand, or have an agent generate one, then read it before anything runs. A node is a few lines.

ags_version: "1.0"
kind: AgenticGraph
id: myorg/add-healthcheck
title: Add a health check endpoint
objective: Expose GET /healthz returning service and dependency status.

entrypoints: [implement]

nodes:
  implement:
    title: Implement /healthz
    description: >
      Add a GET /healthz endpoint returning 200 with {"status":"ok"} when the
      database and cache are both reachable, and 503 with per-dependency detail
      when either is not.
    intelligence:
      tier: standard
    requirements:
      tools: [file_read, file_write, shell_exec]
      permissions: [fs:read:**, fs:write:src/**, shell:exec:pytest*]
    success:
      summary: The endpoint exists and behaves as specified under test.
      criteria:
        - id: tests_pass
          kind: command
          description: The health-check tests pass.
          run: pytest tests/test_healthz.py -q

Validate it against the reference implementation, then hand it to any conformant harness:

python3 -m pip install jsonschema pyyaml
python3 tools/validate_agraph.py path/to/graph.agraph.yaml
python3 tools/validate_agraph.py --strict examples/

If you build harnesses: the repository has a JSON Schema for graph documents and another for run records, five worked examples, invalid fixtures that each name the diagnostic they should produce, and an integration guide covering parsing, scheduling, model routing, criteria evaluation, and human checkpoints. You pick a conformance level and reject graphs that need more, rather than silently ignoring what you cannot do.

  • 0Reader. Parse, validate, resolve dependencies, render a plan. No execution.
  • 1Minimal harness. Tasks and gates, sequence edges, retries, the basic criteria kinds, tier routing.
  • 2Standard harness. Decisions, conditional edges, the full expression language, budget enforcement, real parallelism, escalation.
  • 3Full harness. Loops, maps, subgraphs, judged and external criteria, compensation, run records, checkpoint and resume.

Why it matters

When the decomposition lives inside a harness, four things follow. You cannot review the plan before the tokens are spent. You cannot move it to another tool. Completion is whatever the model claims it is. And every task gets the same model, which either overspends on trivia or underspends on the one architectural decision that mattered.

Making the plan a file fixes all four at once. It becomes reviewable in a pull request, diffable across revisions, portable between harnesses, and checkable against criteria a machine can run. The tier field is the quiet win: a graph states how hard each piece of work is, and the harness maps tiers to models through its own routing profile, so a plan written today still routes correctly when next year's models arrive.

03 / Enterprise

Loro

A Python CLI agent harness for enterprise coding, governed data work, and productivity tasks. Loro is Spanish for parrot: a social bird that listens, learns, and helps knowledge move across a group.

What it is

Loro is the same idea as MagAgent pointed at a different problem. A developer harness optimizes for speed in one person's terminal. An enterprise harness has to answer questions afterward: who ran this, under whose identity, with whose approval, against which policy, and what did it touch.

  • Identity context resolved from configuration and environment, with managed required fields propagated into audit and session records.
  • Identity-bound approvals with once, session, and deny prompts, plus replay protection.
  • Permission policy over normalized filesystem, shell, Git, memory, catalog, provider, and MCP resources, with loro policy explain to show why a decision was made.
  • Subprocess sandbox profiles with minimized environments, bounded runtime and output, and optional Bubblewrap enforcement.
  • Runtime budgets covering model bytes, tokens, cost, and tool calls.
  • A hash-chained audit log: versioned JSONL with process locking and a SHA-256 chain, an authenticated HTTP sink, bounded buffering with retry, and audit doctor, flush, and verify commands.
  • Governed memory, local and shared, with Postgres and Apache Iceberg adapters where shared writes are explicit-only and draft-gated, plus read-only Apache Polaris catalog discovery.
  • Layered configuration from system, user, project, local, and runtime sources, with enterprise-managed overlays that can be required and pinned by SHA-256.

It also generates artifacts, Markdown and DOCX documents, PPTX decks, and XLSX or CSV spreadsheets, each with a provenance sidecar recording the prompt preview, generated paths, assumptions, and generator metadata. It speaks MCP as a client and can serve a least-privilege read-only subset as a server.

How to use it

Install, configure a provider, then run the setup wizards for the governance pieces your organization needs. There is a mock provider so a first run needs no API key at all.

python -m pip install loro-agent
loro configure
loro doctor

loro setup identity
loro setup approvals
loro setup sandbox
loro setup audit

loro run "Inspect README.md and suggest the next three improvements."
loro audit verify

For work that needs explicit scheduling and approval, go through a graph instead of a single prompt. Loro implements AGS at conformance level 3, including durable resume, model-tier routing, harness-evaluated criteria, gates, branches, bounded loops and maps, subgraphs, parallel execution, fallbacks, and compensation.

loro graph generate "Create a release readiness report" --out release.agraph.yaml
loro graph validate release.agraph.yaml --strict
loro graph plan release.agraph.yaml
loro graph run release.agraph.yaml --dry-run

Why it matters

Agentic coding stalls in regulated environments for a reason that has nothing to do with model quality. The blocker is evidence. A team can rarely say which identity authorized a write, what the policy was at that moment, or prove the record has not been edited since. Loro is built so those answers exist by default rather than being reconstructed later.

Worth saying plainly: shipping this in a portable, provable form is what the project covers. Identity-provider integration, production sandbox validation, retention, destination immutability, and an approved external-checker registry are deployment concerns that belong to the adopting organization. The repository documents that boundary instead of implying the box is checked.

04 / The shape of it

How the pieces fit

The spec is the contract between them. Everything else is an implementation choice you get to make separately.

  1. 01

    AGS is the interchange format

    A graph is a file. It can be written by a person, generated by an agent, reviewed in a pull request, and stored next to the code it describes. Nothing in the normative model names a vendor, a model, or a runtime.

  2. 02

    MagAgent and Loro are harnesses that adopt it

    Both implement conformance level 3. The same .agraph.yaml runs in either one: a developer can iterate on a graph locally in MagAgent, and the same file can execute inside Loro under identity, approvals, and audit when it reaches an environment that requires them.

  3. 03

    MagGraph is the memory underneath

    A graph describes one job. MagGraph holds what accumulates across jobs: project conventions, past decisions, the shape of a codebase. Markdown nodes in Git, so the memory is reviewable the same way the plan is.

  4. 04

    Nothing here requires the rest of it

    Implement AGS in your own harness and never touch Mag or Loro. Use MagGraph as a memory layer under a completely different agent framework. The point of writing the format down was to make the pieces separable.

Building a harness Implementation reports are the most useful contribution to the spec right now. If you build against AGS and something is awkward to express, that is a spec bug worth filing at agentic-graph-spec.

05 / Questions

Common Questions

What is the Agentic Graph Specification?

AGS is an open format for writing down how a project is decomposed into agentic work. A graph is a directed acyclic graph whose nodes are bounded agentic loops. Each node carries a brief, typed inputs and outputs, success criteria the harness evaluates, an intelligence tier, the tools and permissions it may use, and budgets. It serializes to JSON or YAML and any conformant harness can run it.

Why write the plan down instead of letting the agent plan internally?

A plan that lives only inside a harness cannot be reviewed before the tokens are spent, cannot move to another tool, and cannot define completion in checkable terms. As a file it becomes reviewable, diffable, portable, and routable, so each node gets a model sized to the work.

What is the difference between MagAgent and Loro?

Both are AGS level 3 harnesses. MagAgent is the developer harness: terminal-native, local-first, backed by MagGraph memory, with recipes, sub-agents, plugins, and chat gateways. Loro is the enterprise harness: identity, approvals, permission policy, sandbox profiles, budgets, a hash-chained audit log, and governed shared memory over Postgres or Apache Iceberg.

Do I have to use all three?

No. AGS is implementation-neutral by design, MagGraph works under any agent framework through its Python API or MCP server, and either harness is useful on its own. They are built to compose, not to lock together.

Is AGS stable enough to build on?

AGS 1.0 is a draft standard. The spec, schema, reference validator, and examples are checked against each other by the repository test suite, but it has not yet been through multiple independent implementations. The versioning policy is normative: minor releases stay backward compatible and deprecated fields survive at least one minor release before removal.

How do I follow the work?

Everything is public on GitHub. Issues and pull requests are open on all four repositories, and the fastest way to reach me about any of it is dev@alexmerced.com.

06 / Start here

Pick a starting point

Read the spec, install an agent, or go back to the rest of what I build.

Read the spec

Start with the minimal example, then the canonical one, then SPEC.md. About an hour to understand the whole model.

agentic-graph-spec

Try an agent

MagAgent for a developer terminal, Loro when the work needs identity, approvals, and an audit trail.

MagAgent Loro

See the rest

The lakehouse tooling, the books, and everything else on the main page.

All Projects Get in Touch