lema · docs

Quickstart

lema-mcpis 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 coding agent that asks. Local, no account.

Step 1

Wire your repo

npx lema-mcp init writes a ready .mcp.json, an AGENTS.md, a guard hook, and a nudge hook into your repo. Already have a config? Point lema straight at any repo with ADRs via --repo — no account, no network beyond fetching the repo.

Leave --adr-dir off and it auto-discovers docs/adr and the like.

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

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.

  • --openspec-dir

    OpenSpec root to read alongside ADRs (a local ./openspec directory is auto-detected).

  • --capture-file

    The local decision store propose / record_decision append to (default .lema/decisions.jsonl).

Step 2

Capture as you decide

As decisions get made, propose writes them — the chosen option and the alternatives that were rejected — into the graph, and check_decided surfaces what’s already settled. The guard and nudge hooks installed by initwire this into your agent’s loop. See the tools reference for the full set.

How that loop fires depends on the client, and we say so plainly. Claude Code runs the guard hook, so the check is automatic — lema hands the agent the relevant decisions and warns before a change. Cursor, Codex, and other MCP clients don’t run hooks, so lema is a tool your agent calls when it reaches a design choice — the same record, but the agent decides when to look.

Step 3

Ask the graph

Before writing code, an agent calls search_decisions and gets back tight, typed claims — each carrying its source — not whole documents.

agent › why did React move from classes to Hooks — and what was ruled out?

  • chosen· reactjs/rfcs#68

    Hooks let function components hold state and lifecycle, so stateful logic can be reused without wrapper components.

  • rejected· reactjs/rfcs#68

    A mixins-style sharing mechanism was ruled out before Hooks — name collisions and implicit dependencies.

  • constraint· rules of hooks

    Hooks are called at the top level in the same order each render — never inside conditionals or loops.

  • consequence· reactjs/rfcs#68

    Classes stay supported; Hooks were additive and opt-in, not a migration mandate.

The rejectedclaim — the why-not — is the part no other tool surfaces: the agent learns what was already argued and ruled out, so it doesn’t reopen it.

Connect your repoTools reference