Meridian

The agent doesn't have memory. The graph does.

Meridian is a task-graph + autonomous worker loop for coding agents. You write a phase plan; the agent queries the graph for the next task, exports its own prompt, locks the task, implements it, marks it done, and pulls the next one. You sit back, hit next, and review.

Status: alpha. Single-agent, local-only, CLI. No LLM is bundled — bring your own.

---

Why this exists

Most "agent frameworks" are stateless: one LLM call dressed up with tool wrappers. The moment the model crashes or you start a new session, all context is gone.

Meridian inverts that. The state lives in a JSON graph on disk. The agent is disposable. Any model can pick up the work mid-stream because the next task, its files, its acceptance criteria, and its blockers are all readable with cat tasks.json | jq.

That's the whole moat. Everything else is plumbing.

The loop

┌──────────────────────────────────────────────────┐
│  .meridian/graph.json   (source of truth)        │
└────────────────────────┬─────────────────────────┘
                         │
              ┌──────────▼──────────┐
              │   MCP server        │  HTTP over the graph
              └──────────┬──────────┘
                         │
              ┌──────────▼──────────┐
              │   Agent loop        │  query → lock → execute → complete
              └──────────┬──────────┘
                         │
              ┌──────────▼──────────┐
              │   Executor          │  writes files (LLM goes here)
              └─────────────────────┘

Quickstart

git clone https://github.com/YOU/meridian
cd meridian
npm install
npm run server   # terminal 1: starts the MCP server
npm run dev      # terminal 2: runs the agent loop

The agent will walk through .meridian/tasks.json, moving each task from todo → in_progress → done. See examples/phase-01-demo for a real phase end-to-end.

What works today

• Flat-file task graph (.meridian/tasks.json)
• HTTP task interface (GET /tasks, POST /lock/:id, POST /complete/:id)
• Sequential agent loop
• Template-based executor (drop in your LLM here)

What doesn't work yet

• Dependency resolution (DAG ordering)
• Multi-agent locking with leases
• LLM-backed executor (the obvious next step)
• Validation layer (lint/test gates)
• Tree-sitter safe edits

See docs/architecture.md for the honest scope.

Contributing

This is going to get criticized — that's the point of being open. Read CONTRIBUTING.md before opening a PR. The short version: small PRs welcome, big architectural rewrites need an issue first.

License

MIT. See LICENSE.