From nothing to a rehydrated session.

You need an enabled Mneia account and Node.js 20 or newer. Access is granted in stages from the waitlist, and the packages install once your account is enabled.

You do not need a model provider key. Mneia pays for the inference a checkpoint runs, so there is nothing to configure and nothing of ours on your provider bill.

Two packages. The CLI is the surface you drive; the MCP server is the surface your agent drives. Most people install both, globally, because both are used across repositories.

npm install -g @mneia/cli @mneia/mcp-server

mneia --version

The CLI installs the mneia binary and the MCP server installs mneia-mcp. You never run mneia-mcp yourself — an MCP client starts it over stdio.

Interactively, mneia login approves the machine in a browser and writes a token to ~/.mneia/credentials. Non-interactively — CI, a container, an MCP client started without a shell — set MNEIA_TOKEN in the environment instead. The environment variable wins when both are present.

mneia login

# or, where there is no browser:
export MNEIA_TOKEN="<token>"

Set the token value alone — no Bearer prefix, no quotes, no trailing newline. A blank MNEIA_TOKEN is rejected rather than silently ignored, because an unresolved CI secret is the usual cause and falling back quietly would hide it.

Run mneia init in the repository root. It derives the project slug from the directory name unless you name one.

cd ~/code/payments
mneia init --workspace acme --project payments

It does three things, and says so:

• Writes .mneia/config.json, binding this directory to a workspace and a project. Commit it — the binding is a property of the repository, not of your laptop.
• Reads the AGENTS.md, CLAUDE.md, and .cursor/rules files you already keep, and imports the constraints in them, so the project does not start empty.
• Writes a generated section into AGENTS.md inside a fence it owns. Nothing outside that fence is touched, and editing inside it is detected rather than overwritten.

If the repository is already bound and you mean to rebind it, add --force. Without it, a conflicting --workspace or --project is refused rather than silently re-pointing a repository at a different project.

The MCP server speaks stdio, so any MCP client can start it. Register it once per client. Claude Code, Cursor, and Codex all take the same shape:

{
  "mcpServers": {
    "mneia": {
      "command": "mneia-mcp",
      "env": {
        "MNEIA_TOKEN": "<token>"
      }
    }
  }
}

The server resolves its configuration before it accepts a connection, so a missing token or a malformed endpoint stops it at startup rather than on the first tool call. MCP clients tend to bury server stderr — if the tools do not appear, read the client’s log pane before assuming the server is broken.

Drop the env block if you ran mneia login; the server reads the same credentials file the CLI wrote. The project binding comes from .mneia/config.json in the working directory, so the agent inherits it without being told.

This is the loop. Everything else is detail.

1. Start the task with a rehydrationThe agent calls mneia_rehydrate with the task it is about to start. It gets back the active constraints it must not violate, the decisions already made and why, the open questions, and what was recently superseded. Call it unconditionally — it is one indexed query, it is not metered, and the p95 budget for it is 300ms.
2. Work as you normally wouldNothing about the inner loop changes. When a decision is settled mid-session and you do not want to risk losing it, the agent calls mneia_assert on that one item rather than waiting.
3. Checkpoint at the boundaryAt the end of a task or a day, the agent extracts the candidate decisions, constraints, and open questions from the session and hands them to mneia_checkpoint as one batch. Items that are load-bearing, or that supersede something already there, come back in a pending queue for a human to confirm — they are never written on an agent’s say-so.
4. Confirm what mattersSurface the pending queue and confirm the load-bearing items. This is the step that makes the record trustworthy later, and it is the one worth not skipping.

From the terminal the same loop reads:

mneia brief "migrate the ledger writes to the v2 schema"

# ... work ...

mneia checkpoint
mneia status

• Read Concepts for the vocabulary — item kinds, provenance, superseding, and why a rejected approach is kept rather than deleted.
• Read the CLI reference for every command, flag, JSON shape, and exit code.
• Read the MCP server reference for the four tools and when each one is the right call.

Handoffs — producing a receivable artifact when work changes hands, and picking one up — ship after the current milestone. The CLI and the MCP server both refuse those surfaces by name today rather than pretending they exist.