lema · docs

Connect your repo

The Quickstart runs lema locally over one checkout. Connecting a repo moves the graph to hosted: lema imports your repo’s decision record once, keeps it, and serves it to every agent session — the same cited answers and the same honest abstentions, over your own record instead of the public commons.

Step 1

Sign in and connect

Continue with GitHub — your org is provisioned the instant you sign in, nothing to name or configure. Then point lema at a repo: GitHub’s own consent screen asks the permission, you pick the repo, and the import runs while you do something else. Decisions and claims tick up live; if the import truncates, the cut is stated on the page — a full-history backfill is a Pro switch, never a surprise.

Step 2

Mint an API key

Keys live at /login/account/api-keys. A key answers over the workspaces you can see, so minting needs at least one connected repo — the page points you back to connect one first if none exists. The key is shown once, at mint time, prefixed lema_live_.

One rule of identity underneath: sign-in is for humans; lema_live_ keys are for agents. It matters for the write path below.

Step 3

Point lema-mcp at your graph

The same lema-mcp binary from the Quickstart switches to hosted mode when it finds an API URL and key. The recommended channel is the credentials file — the secret lives in a 0600 dotfile in your home directory, never in the repo.

The .mcp.json env block works too for per-project setups — but it embeds the key in a file that usually gets committed. Don’t commit a live key; prefer the credentials file for anything shared.

After that, lema matches the checkout’s verified Git remote to a connected repository and its Project — no workspace id to copy. Run npx lema-mcp doctor context to see the receipt. LEMA_WORKSPACE_ID remains an optional override when you need to pin a target explicitly.

~/.config/lema/credentials — recommended
LEMA_API_URL=https://api.lema.sh
LEMA_API_TOKEN=lema_live_…
.mcp.json — per-project alternative
{
  "mcpServers": {
    "lema": {
      "command": "npx",
      "args": ["-y", "lema-mcp"],
      "env": {
        "LEMA_API_URL": "https://api.lema.sh",
        "LEMA_API_TOKEN": "lema_live_…"
      }
    }
  }
}

What changes over hosted

  • ask and get_state_brief appear — a synthesized, cited answer over your own decision graph, and the scoped State Brief for a run (also as the lema://brief resource). See the tools reference.
  • resolve, check_decided, and check_approach adjudicate against your settled record — the ruled-out alternatives your own team already argued, not just the public commons.
  • propose (and its alias record_decision) pushes captures into your Project. A solo owner’s push can open recall immediately; a team push lands as a proposed draft. Either way, only a person accepting it in the app makes it binding — a key can never silently commit your team.

Free and Pro

Everything on this page works on the Free plan — connect, import, mint a key, serve your agents. Pro lifts the daily allowances and unlocks full-history backfill on imports; the upgrade lives in your account page and the fee is shown at checkout before you pay. The numbers are on Plans & usage.

Tools referencePlans & usage