lema · quickstart

Give your coding agent the why.

lema is the system of record for why. lema-mcp is the local, database-less MCP server that serves a repo’s decisions — the chosen approach, the constraints, the consequences, and the alternatives that were ruled out — to any agent that asks.

“We are drowning in information, while starving for wisdom.”— E. O. Wilson

local · ~10 minutes · no account

Quickstart

Point it at a repo

npx is the front door. Point lema at a repo that already has ADRs and you get a queryable MCP endpoint — no team buy-in, no account, no network beyond fetching the repo.

$ npx lema-mcp --repo github.com/your-org/your-repo

Already have the decisions on disk? Run it against a local ADR directory — leave --adr-dir off and it auto-discovers docs/adr.

$ npx lema-mcp --adr-dir docs/adr

Flags

  • --repo

    github.com/org/repo to fetch (public; GITHUB_TOKEN for private), or a label for local --adr-dir mode.

  • --adr-dir

    ADR directory (local path, or in-repo subpath with --repo). Empty auto-discovers docs/adr, docs/decisions, and the like.

  • --ref

    git ref or branch to fetch from (default: the repo's default branch); remote --repo only.

  • --pattern

    ADR filename regex (default matches NNNN-*.md / NNN_*.md); widen it for other conventions.

Add it to your agent

One entry in .mcp.json

Wire lema-mcp in as a stdio MCP server — Claude Code, Cursor, any MCP-aware client — and the tools show up for the agent: four to read your decisions, two to record and enforce them.

.mcp.json
{
  "mcpServers": {
    "lema": {
      "command": "npx",
      "args": ["lema-mcp", "--repo",
               "github.com/your-org/your-repo"]
    }
  }
}

Read and enforce

What the agent can call

  • search_decisions

    Search this repo's decisions and return the most relevant atomic claims (chosen/rejected/constraint/consequence) with their source ADR. Call this BEFORE writing or changing code to learn the constraints and what was already ruled out.

  • get_decision

    Get one decision's full body, status, and edges by its ADR number — drill down after search_decisions surfaces a relevant ref.

  • list_decisions

    List the architecture decisions recorded in this repo, optionally filtered by status.

  • get_decision_graph

    Traverse typed edges (supersedes, superseded_by, depends_on, related_to) from a decision to find connected decisions.

  • record_decision

    Record a decision you just settled — the chosen option AND the alternatives you rejected, with why each was killed. What you record becomes durable context for the next agent and is enforced: rejected and superseded options come back CLOSED so they are not re-proposed.

  • check_decided

    Before proposing a direction — a library, an approach, a design — check whether it is already decided and CLOSED. Returns the prior decisions that rule the option out; if anything comes back, surface the existing decision instead of re-proposing it.

Example

Ask, and get sourced claims

The agent calls search_decisions before it writes code. It gets back tight, typed atoms — not whole documents — each carrying its source ADR.

agent › why did we choose Postgres — and what did we rule out?

  • chosen· ADR-0007

    Postgres is the system of record — one relational store for decisions, edges, and the atom layer.

  • rejected· ADR-0007

    A document store (Mongo) was ruled out: typed edges between decisions need relational integrity, not denormalized blobs.

  • constraint· ADR-0008

    Run N-1 Postgres in production; no betas or RCs.

  • consequence· ADR-0033

    pgvector lives in the same instance, so the hosted atom layer adds no second datastore to operate.

That rejected claim — the “why-not” — is the part no other tool surfaces. The agent learns not just what you chose, but what was already argued and ruled out, so it doesn’t reopen it. Drill in with get_decision or follow the typed edges with get_decision_graph.

Why it matters

The reasoning behind a repo’s hard decisions is scattered across PRs, threads, and people’s heads — information without wisdom. lema makes it queryable at the moment of the next change, so agents stop re-litigating settled decisions and stop breaking rules they were never told. The why is finally there when it matters.