Docs

Connect an agent in one line.

Mentat is a stateless Model Context Protocol server over Streamable HTTP, plus a CLI that can run the same tools over stdio against a graph committed in your repository.

Connect

CLAUDE CODE, HOSTED DEMO GRAPH

claude mcp add --transport http mentat https://trymentat.pages.dev/mcp

CLAUDE CODE, YOUR OWN GRAPH

claude mcp add --transport http mentat https://trymentat.pages.dev/mcp \ --header "Authorization: Bearer mtk_your_key"

CLAUDE CODE, LOCAL GRAPH OVER STDIO

claude mcp add mentat -- npx -y @mentatlabs/cli mcp

CURSOR, WINDSURF, CODEX, ANY MCP CLIENT

{ "mcpServers": { "mentat": { "type": "http", "url": "https://trymentat.pages.dev/mcp", "headers": { "Authorization": "Bearer mtk_your_key" } } } }
Without an Authorization header you get the read-only demo graph. It already contains a contradiction between two engineers, so the first relevant call on src/routes/orders.ts returns a real block rather than an empty state.

Tools

Fourteen of them. relevant is the one that matters; the rest exist so a conflict can be resolved without leaving the editor.

relevant(file_path, symbols?)reads

What governs this file, resolved, or a block.

Returns the decisions that govern a path, ordered most specific first, each with its reason and the state of the assumptions it rests on. When two active decisions disagree about the path, returns a block naming both authors instead. Agents are instructed to stop and report it rather than choose.

record(constraint, justification?, scopes?, assumption?, statement_type?)writes

Log a rule the user just stated.

Lands as proposed. Nothing governs a file until a human confirms it. If no justification is given the tool says so in its reply, because a rule with no stated why cannot be arbitrated against a competing one and cannot ever expire.

conflicts(scope?)reads

Every derived contradiction, with provenance.

Runs the three-stage pipeline over the graph and returns what survived, with the per-stage counts. There is no way to enter a conflict by hand.

resolve(conflict_id, action, winner_id?, scopes?, expires_at?, reason?)writes

Supersede, carve out, or retire.

`except` is usually what people mean: both decisions stay active and a scoped, expiring hole is cut in the broader one. An expiry is required, because an exception without one is a decision reversal nobody wrote down.

assumptions(status?)reads

What the decisions are standing on.

Each assumption with how long since it was verified, how it is verified, and every decision resting on it. Assumptions verified only manually decay to questioned after 60 days.

break_assumption(assumption_id, note?)writes

Kill a premise, cascade to dependents.

Marks the assumption broken and questions every decision that rests on it in one pass. A questioned decision loses arbitration against a holding one rather than blocking.

watch_assumption(assumption_id, query, comparator?, threshold?, unit?)writes

Point a premise at a metric so it can break itself.

The threshold is usually already in the assumption's own sentence, so only the query is required. Mentat will not invent a metric name: if the sentence carries no number and none is supplied, the tool asks rather than guessing. Defaults to breaking after two consecutive breaching readings, because one spike is not a broken premise.

check_assumptions()writes

Sample every monitor now and apply what it says.

Normally runs on a schedule. A premise that breaches its threshold for long enough is marked broken and cascades exactly as a human break does. An unreadable metric is recorded as unreadable, never as a failure, because training a team to ignore the cascade is worse than missing one break.

enforce(directory?)reads

Compile the checkable decisions into rules CI runs.

Emits dependency-cruiser, ESLint, and literal-check configuration, each rule carrying the justification and the author so a failed build explains itself. Only code_inferable and structural decisions are ever compiled; everything else is returned in `skipped` with the reason, because silence about an unenforced rule is how a team comes to believe CI is checking something it is not.

amend(decision_id, reason, constraint?, scopes?, polarity?, …)writes

Change one field without replacing the decision.

The decision keeps its id, its author, and its history, so the resolution record and the assumptions it rests on survive the edit. A reason is required: an edit to a governing rule with no stated why is a decision reversal nobody wrote down. Returns the diff and says whether the contradiction survived the change.

history(decision_id)reads

What changed, who changed it, and why.

Every amendment to one decision, oldest first, with before and after values. This is the audit answer: what a rule said when some code shipped rather than what it says now. Append-only, and nothing in the engine reads it to decide anything, because an audit trail that changes behaviour is one somebody has an incentive to edit.

queue(state?)reads

Open contradictions, with owners and an age.

Both authors are owners, in the order their names sort. The list is ordered by age, measured from the first time an agent was actually stopped, not from when the decisions were written. There is no priority column and no assignee, because either one would be Mentat picking a side.

compile(directory?, replacing?)reads

A scoped AGENTS.md for one directory.

Enforceable statements become rules; infrastructure and intent-oriented ones become context. Unresolved conflicts are printed as unresolved rather than silently decided. Pass the current file to get the size delta.

coherence()reads

One number, out of 100.

Weighted across internal consistency, assumption freshness, whether decisions carry a reason, and how narrowly they are scoped. Every point lost names the decision or assumption that lost it.

Scope algebra

Four levels, resolved most-specific-wins. Levels one through three are deterministic set arithmetic; the fourth is the only place a model sits inside the resolution path, and it is cached and treated as unresolved rather than guessed when it fails.

LevelWritten asExampleResolution
1 · globsrc/routes/**src/routes/orders.**Deterministic. Literal segments outrank wildcards.
2 · modulemodule:paymentsmodule:ordersDeterministic, from the workspace module map.
3 · symbolsymbol:Class.methodsymbol:OrderRepository.writeDeterministic. Nesting counts as overlap.
4 · semanticsemantic:...semantic:any write path to the orders tableLazy, model-resolved, cached. Unresolved never matches.

CLI

Everything works offline against .mentat/graph.json, which is meant to be committed. A team's decisions are a team artifact and should be reviewed in pull requests like everything else. It is published on npm as @mentatlabs/cli, so npx -y @mentatlabs/cli init is the whole install, or use the hosted endpoint above and skip it. The REST API is described in the developer portal.

mentat initCreate the graph, seeded from CLAUDE.md, AGENTS.md, and any ADRs
mentat relevant <path>What governs this file, or a block naming who disagrees
mentat conflictsDerived contradictions across the graph. Exits non-zero if any
mentat assumptionsWhat the decisions stand on, and how stale each one is
mentat monitorsWhich premises check themselves, and what they last read
mentat monitors checkSample every monitor now. Non-zero if a premise died
mentat queueOpen contradictions, with owners and an age
mentat enforce --writeGenerate the lint and dependency rules CI runs
mentat benchThe decision-outcome benchmark, baselines included
mentat scoreCoherence out of 100, with the things costing points
mentat ingestMine ~/.claude/projects sessions for decisions
mentat review --allPromote proposals. Nothing governs a file until you do
mentat amend <id>Change one field of a decision. A reason is required
mentat history <id>Every amendment, with who changed it and why
mentat compile --checkFail CI when a committed AGENTS.md is out of date
mentat mcpRun as an MCP server over stdio

SDK

Two shapes, because there are two real integrations. A typed client for a hosted workspace, and the engine itself running in your process against a graph you hold. The second is the one most people want: the pipeline is pure, so blocking a commit on a contradiction needs no network at all.

THE ENGINE, LOCALLY. NO ACCOUNT, NO KEY, NO REQUEST.

import { runLocally } from "@mentatlabs/sdk"; import { deterministicAdjudicator } from "@mentatlabs/providers"; const mentat = runLocally({ graph, adjudicator: deterministicAdjudicator }); if (await mentat.blocked("src/routes/orders.ts")) { console.error("Two active decisions disagree about this file."); process.exit(1); }

A HOSTED WORKSPACE

import { createClient } from "@mentatlabs/sdk"; const mentat = createClient({ token: process.env.MENTAT_TOKEN! }); const { block, constraints } = await mentat.resolve("src/routes/orders.ts");

WHAT THE CLIENT EXPOSES

resolveWhat governs a path, or the block that should stop you
queue / metricsOpen contradictions and the coherence numbers
enforceThe generated CI configuration, ready to write
watchAssumptionPoint a premise at a metric
checkMonitorsSample them and apply what they say
precedentWhat other teams did, or null below the anonymity floor
tool(name, args)Any MCP tool this surface has not wrapped yet

Every failure is a MentatError carrying the status, a code, and the server’s own message. A refusal the API explained in a sentence should not arrive as “request failed with 409”. Transport failures get status zero, so a retry loop can tell them apart.

Questions

Do I need an account?

No. Without a key the MCP endpoint serves a read-only demo graph that already contains a real contradiction. Run `npx @mentatlabs/cli init` for your own graph, which is a JSON file in your repository, or `mentat init --hosted` for a shared one. There is no signup form anywhere.

Do I need an Anthropic API key?

No. Stage three of conflict detection falls back to a deterministic adjudicator, which is also what the precision test is measured against. A key buys recall on cases where reading the justification beats reading the sentence structure.

How is this different from a CLAUDE.md linter?

Linters catch duplicate and contradictory lines inside one file. Mentat resolves scope collisions between decisions made by different people at different times, tracks whether each decision's premise still holds, and answers at the agent's read moment rather than at commit time.

How is this different from an AI code reviewer?

Reviewers check code against decisions and treat the decision set as ground truth. Mentat checks decisions against each other and against time. Pull-request violation detection is well funded and crowded; Mentat ships it late and never leads with it.

What stops it from inventing conflicts between colleagues?

Three gates in order. Scopes must be able to cover the same file, computed as set arithmetic with no model involved. The constraints must pull on the same axis in opposed directions. They must share a salient subject. Only survivors reach an adjudicator, and only a confidence above 0.75 blocks. A test suite asserts that twenty unrelated decision pairs produce exactly zero conflicts.

Does a monitored assumption need Prometheus?

It needs a metrics backend to actually read a number, and Prometheus is the only one shipped, deliberately: five half-working adapters teach a team the cascade is unreliable, and an unreliable cascade is worse than a timer because people stop reading it. Without one, monitors are listed and reported as unread rather than silently passing. A `static:` monitor records a reading a human took by hand and runs through the same evaluation and cascade.

What leaves my workspace for cross-organisation precedent?

Nothing a human wrote, and only if you turn it on. A share record carries an axis, two directions from a closed vocabulary, up to three concept keys defined in this repository, which resolution was applied, a bucketed duration, and whether it was later undone. No constraint text, no justification, no author, no scope, no repository, and no id that survives outside your workspace. Reading needs no opt-in but returns nothing until five distinct organisations have contributed the same shape of disagreement.

Why is your own benchmark score low?

Because it is the real one. Our predictor catches half the reversals and never cries wolf, both trivial baselines sit in the same table, and Matthews correlation is the headline so that answering “nothing ever changes” scores exactly zero. A benchmark whose author tops it convinces nobody.

Where does the data live?

The local graph is `.mentat/graph.json` in your repository, which is meant to be committed and reviewed in pull requests like anything else. A hosted graph lives in a Cloudflare Durable Object, keyed by a bearer token. Transcripts are never stored; only the extracted constraints and a pointer back to the session are.

Still curious about the research behind the claims? Every figure is sourced.