Beside your tools, never above them.

Mneia is not an agent, a runtime, or a framework. It is a context layer that every surface reaches through the same verbs, which is what lets a handoff survive crossing from one tool to another.

8 min read · 7 sections

Why neutrality is structural

A handoff that only works inside one vendor’s tool is not a handoff - it is a session feature. The whole claim depends on the artifact surviving the crossing: written by an agent in one client, received by a person in another, weeks later.

Model providers are structurally incentivised against that. Every one of them wants its own instructions file and its own memory, and none of them has a reason to make your context portable to a competitor. That gap does not close.

MCP clients

The MCP server is the primary integration. It speaks stdio and exposes no vendor-specific behaviour, so any MCP-capable client can start it with the same configuration.

Connect your agent

Codex CLI and desktop

Install once for Codex. The CLI and desktop app read the same MCP registration.

View complete setup prompt

Set up MNEIA for Codex CLI and desktop in this repository using only supported customer surfaces.

1. Verify Node.js 20.11 or newer is installed.
2. Run: npm install -g @mneia/cli @mneia/mcp-server
3. Run: mneia login
4. Run: mneia init
5. Run: mneia mcp install --client codex --yes
6. Restart Codex CLI and desktop if it was already open.
7. Call mneia_rehydrate for the current task and report the workspace, project, slice ID, returned item count, and token usage.

Do not edit credentials. Do not commit tokens or put them in project files. Do not call private endpoints. Do not inspect the database. Do not bypass the MNEIA CLI or MCP tools. When writing MCP configuration, preserve every unrelated client configuration and server entry. If a supported command fails, stop and report that exact failure instead of working around it. Do not claim setup is verified until mneia_rehydrate succeeds.

Recommended

Automatic setup

mneia mcp install --client codex --yes

Manual fallback

Codex native fallback

codex mcp add mneia -- mneia-mcp

Verify: Restart Codex, then ask it to call mneia_rehydrate for the current task.

Connect your agent

Claude Code

View complete setup prompt

Set up MNEIA for Claude Code in this repository using only supported customer surfaces.

1. Verify Node.js 20.11 or newer is installed.
2. Run: npm install -g @mneia/cli @mneia/mcp-server
3. Run: mneia login
4. Run: mneia init
5. Run: mneia mcp install --client claude-code --yes
6. Restart Claude Code if it was already open.
7. Call mneia_rehydrate for the current task and report the workspace, project, slice ID, returned item count, and token usage.

Do not edit credentials. Do not commit tokens or put them in project files. Do not call private endpoints. Do not inspect the database. Do not bypass the MNEIA CLI or MCP tools. When writing MCP configuration, preserve every unrelated client configuration and server entry. If a supported command fails, stop and report that exact failure instead of working around it. Do not claim setup is verified until mneia_rehydrate succeeds.

Recommended

Automatic setup

mneia mcp install --client claude-code --yes

Manual fallback

Claude Code native fallback

claude mcp add --transport stdio --scope user mneia -- mneia-mcp

Verify: Restart Claude Code, then ask it to call mneia_rehydrate for the current task.

Connect your agent

Claude Desktop

Write the MNEIA stdio server into Claude Desktop’s global MCP configuration.

View complete setup prompt

Set up MNEIA for Claude Desktop in this repository using only supported customer surfaces.

1. Verify Node.js 20.11 or newer is installed.
2. Run: npm install -g @mneia/cli @mneia/mcp-server
3. Run: mneia login
4. Run: mneia init
5. Run: mneia mcp install --client claude-desktop --yes
6. Restart Claude Desktop if it was already open.
7. Call mneia_rehydrate for the current task and report the workspace, project, slice ID, returned item count, and token usage.

Do not edit credentials. Do not commit tokens or put them in project files. Do not call private endpoints. Do not inspect the database. Do not bypass the MNEIA CLI or MCP tools. When writing MCP configuration, preserve every unrelated client configuration and server entry. If a supported command fails, stop and report that exact failure instead of working around it. Do not claim setup is verified until mneia_rehydrate succeeds.

Recommended

Automatic setup

mneia mcp install --client claude-desktop --yes

Manual fallback

claude_desktop_config.json

{
  "mcpServers": {
    "mneia": {
      "command": "mneia-mcp",
      "args": []
    }
  }
}

Verify: Fully quit and reopen Claude Desktop, then call mneia_rehydrate in a new chat.

Connect your agent

Cursor IDE

Add MNEIA to Cursor’s global MCP configuration without editing JSON by hand.

View complete setup prompt

Set up MNEIA for Cursor IDE in this repository using only supported customer surfaces.

1. Verify Node.js 20.11 or newer is installed.
2. Run: npm install -g @mneia/cli @mneia/mcp-server
3. Run: mneia login
4. Run: mneia init
5. Run: mneia mcp install --client cursor --yes
6. Restart Cursor IDE if it was already open.
7. Call mneia_rehydrate for the current task and report the workspace, project, slice ID, returned item count, and token usage.

Do not edit credentials. Do not commit tokens or put them in project files. Do not call private endpoints. Do not inspect the database. Do not bypass the MNEIA CLI or MCP tools. When writing MCP configuration, preserve every unrelated client configuration and server entry. If a supported command fails, stop and report that exact failure instead of working around it. Do not claim setup is verified until mneia_rehydrate succeeds.

Recommended

Automatic setup

mneia mcp install --client cursor --yes

Manual fallback

~/.cursor/mcp.json

{
  "mcpServers": {
    "mneia": {
      "command": "mneia-mcp",
      "args": []
    }
  }
}

Verify: Restart Cursor, open MCP settings, then ask the agent to call mneia_rehydrate.

Connect your agent

Gemini CLI

View complete setup prompt

Set up MNEIA for Gemini CLI in this repository using only supported customer surfaces.

1. Verify Node.js 20.11 or newer is installed.
2. Run: npm install -g @mneia/cli @mneia/mcp-server
3. Run: mneia login
4. Run: mneia init
5. Run: mneia mcp install --client gemini-cli --yes
6. Restart Gemini CLI if it was already open.
7. Call mneia_rehydrate for the current task and report the workspace, project, slice ID, returned item count, and token usage.

Do not edit credentials. Do not commit tokens or put them in project files. Do not call private endpoints. Do not inspect the database. Do not bypass the MNEIA CLI or MCP tools. When writing MCP configuration, preserve every unrelated client configuration and server entry. If a supported command fails, stop and report that exact failure instead of working around it. Do not claim setup is verified until mneia_rehydrate succeeds.

Recommended

Automatic setup

mneia mcp install --client gemini-cli --yes

Manual fallback

~/.gemini/settings.json

{
  "mcpServers": {
    "mneia": {
      "command": "mneia-mcp",
      "args": []
    }
  }
}

Verify: Restart Gemini CLI, then ask it to call mneia_rehydrate for the current task.

Connect your agent

VS Code and GitHub Copilot

View complete setup prompt

Set up MNEIA for VS Code and GitHub Copilot in this repository using only supported customer surfaces.

1. Verify Node.js 20.11 or newer is installed.
2. Run: npm install -g @mneia/cli @mneia/mcp-server
3. Run: mneia login
4. Run: mneia init
5. Run: mneia mcp install --client vscode --yes
6. Restart VS Code and GitHub Copilot if it was already open.
7. Call mneia_rehydrate for the current task and report the workspace, project, slice ID, returned item count, and token usage.

Do not edit credentials. Do not commit tokens or put them in project files. Do not call private endpoints. Do not inspect the database. Do not bypass the MNEIA CLI or MCP tools. When writing MCP configuration, preserve every unrelated client configuration and server entry. If a supported command fails, stop and report that exact failure instead of working around it. Do not claim setup is verified until mneia_rehydrate succeeds.

Recommended

Automatic setup

mneia mcp install --client vscode --yes

Manual fallback

VS Code MCP configuration

{
  "servers": {
    "mneia": {
      "type": "stdio",
      "command": "mneia-mcp"
    }
  }
}

Verify: Reload VS Code, confirm MNEIA is running, then call mneia_rehydrate.

Connect your agent

Windsurf

Add the same local stdio server to Windsurf’s MCP configuration.

View complete setup prompt

Set up MNEIA for Windsurf in this repository using only supported customer surfaces.

1. Verify Node.js 20.11 or newer is installed.
2. Run: npm install -g @mneia/cli @mneia/mcp-server
3. Run: mneia login
4. Run: mneia init
5. Run: mneia mcp install --client windsurf --yes
6. Restart Windsurf if it was already open.
7. Call mneia_rehydrate for the current task and report the workspace, project, slice ID, returned item count, and token usage.

Do not edit credentials. Do not commit tokens or put them in project files. Do not call private endpoints. Do not inspect the database. Do not bypass the MNEIA CLI or MCP tools. When writing MCP configuration, preserve every unrelated client configuration and server entry. If a supported command fails, stop and report that exact failure instead of working around it. Do not claim setup is verified until mneia_rehydrate succeeds.

Recommended

Automatic setup

mneia mcp install --client windsurf --yes

Manual fallback

~/.codeium/windsurf/mcp_config.json

{
  "mcpServers": {
    "mneia": {
      "command": "mneia-mcp",
      "args": []
    }
  }
}

Verify: Restart Windsurf, then ask Cascade to call mneia_rehydrate.

Connect your agent

another supported MCP client

Detect installed clients automatically, or use the standard stdio configuration.

View complete setup prompt

Set up MNEIA for another supported MCP client in this repository using only supported customer surfaces.

1. Verify Node.js 20.11 or newer is installed.
2. Run: npm install -g @mneia/cli @mneia/mcp-server
3. Run: mneia login
4. Run: mneia init
5. Run: mneia mcp install --all --yes
6. Restart another supported MCP client if it was already open.
7. Call mneia_rehydrate for the current task and report the workspace, project, slice ID, returned item count, and token usage.

Do not edit credentials. Do not commit tokens or put them in project files. Do not call private endpoints. Do not inspect the database. Do not bypass the MNEIA CLI or MCP tools. When writing MCP configuration, preserve every unrelated client configuration and server entry. If a supported command fails, stop and report that exact failure instead of working around it. Do not claim setup is verified until mneia_rehydrate succeeds.

Recommended

Automatic setup

mneia mcp install --all --yes

Manual fallback

Generic stdio configuration

{
  "mcpServers": {
    "mneia": {
      "command": "mneia-mcp",
      "args": []
    }
  }
}

Verify: Restart the client, then ask it to call mneia_rehydrate for the current task.

Client differences are normalised at the edge rather than leaking inward. Each client identifies itself and its version on the session, and where it exposes a stable session reference or a deep link back to the original conversation, those are stored too - so provenance can point at the actual conversation rather than at a summary of it.

Where a client exposes only part of that shape, the absence is reported as partial provenance rather than backfilled with a guess. A provenance chain with a hole in it is more useful than one with an invention in it.

Checkpoint sources

Connecting the MCP server is how an agent calls Mneia. Reading a transcript is how mneia checkpoint finds out what a session actually did, and the two are separate: a harness whose transcript Mneia can read does not have to be one Mneia is connected to.

The CLI discovers sessions on the machine, works out which of them belong to this directory, and checkpoints from them. Six sources are read today.

Source	Read from	Notes
`claude-code`	The JSONL transcripts under the projects directory	The reference implementation. Carries a stable session reference
`claude-desktop`	The local agent-mode session directories under the Claude application data folder	Desktop keeps its agent sessions per working directory rather than in one place, so the reader walks for them and reads each with the same parser Claude Code uses. Same transcript format, different location
`codex`	The Codex session files	Recorded with the client name and version the session declared
`cursor`	Cursor’s local store
`gemini`	The Gemini CLI session files
`warp`	The Warp SQLite database, opened read-only	A terminal rather than an agent harness, so its shape is different: conversations rather than transcripts, and the working directory comes from the queries recorded against a conversation. When a conversation began is derived from its earliest query, because the table only records when it was last touched - and a conversation started months ago but touched today would otherwise look new
`file`	A transcript you point at directly	The escape hatch for a harness with no reader

A source that is not installed is not an error. Discovery reports it as unavailable, with the reason, and carries on with the ones that are - so a machine with two harnesses does not fail because it does not have the other four.

With no flags, mneia checkpoint reads the single most recently active session and says how many others it found and did not read. --all-sessions sweeps them; --session <ref> names one, with --source <harness> where two harnesses use the same reference. Each session carries its own watermark, so one you skip today resumes where it was when you do read it.

Discovery reads transcripts that already exist on your machine, at the moment you run a checkpoint. It is not a watcher, there is no background process, and nothing is uploaded until you ask for a checkpoint. A session that began before this repository was bound to a project is out of scope and is not read.

File interop

Teams already keep their constraints somewhere - AGENTS.md, CLAUDE.md, .cursor/rules. Those files are read on init and the constraints in them are imported, so a project does not start empty and nobody has to retype what they already wrote down.

A generated section is written back into AGENTS.md inside a fence Mneia owns. That is what makes the value show up even in a session where the MCP server is not connected at all.

Nothing outside the fence is ever touched. It is your file, in your repository, in your git history.
A hand-edit inside the fence is detected rather than overwritten - the boundary is a tested invariant, not a convention.
If the fence has been damaged, init stops and says so rather than guessing where it used to be.

.mneia/config.json holds the project binding - workspace, project slug, endpoint. No data and no credentials. It is meant to be committed, because the binding is a property of the repository rather than of one laptop. Credentials live in ~/.mneia/credentials, outside the repository, and never enter git.

The web app

Surface	What it is for
Account plane	Signing up, accepting an invitation, and approving a device from `mneia login`
Projects	Creating, renaming, and archiving the bodies of work a workspace is tracking
Decision browser	Reading the project record - what was decided, by whom, and what it replaced
Timeline	The bi-temporal view: what the project believed on a given date, rather than only what it believes now
Review queue	Confirming the items a checkpoint held back, away from the terminal
Handoffs	The project inbox, and the artifact page whose link you paste to a colleague
Team	Membership, invitations, roles, and the join link. This is where a workspace is actually administered
Tokens	Every live token in the workspace, and the one control that revokes any of them
Billing	The plan, the seats, the prepaid balance, and the usage meter

/docs/web-app covers each of those in full, including what the app deliberately does not do.

The web app is deliberately thin. It is a view onto the same verbs rather than a second product - if a surface here needed a verb the CLI and the MCP server do not have, that would be the signal it had started becoming something else.

Conflict detection runs and is recorded; conflict resolution does not yet have a surface in the app, and neither does the CLI. /docs/conflicts describes the rules it will follow, and says plainly what is not built.

CI and automation

An ephemeral runner with no disk is an ordinary client rather than a special case. Set MNEIA_TOKEN, and every command behaves exactly as it does on a laptop - which matters as more work is done by agents inside pipelines rather than beside a person.

env:
  MNEIA_TOKEN: ${{ secrets.MNEIA_TOKEN }}

steps:
  - run: mneia brief "$TASK" --json > context.json
  # ... agent runs ...
  - run: mneia checkpoint --trigger task_boundary --json

Exit codes separate a network failure from a missing binding from a bad token, so a pipeline can retry the first and fail fast on the other two rather than treating every non-zero exit as one event.

What is deliberately not here

The boundary is as much a part of the design as the surface. Mneia sits beside orchestration frameworks and never above them.

Not this	Why
Agent orchestration or a runtime	We sit beside LangGraph, CrewAI, and Claude Code. Locking your agents into our runtime would trade neutrality for control.
Observability, tracing, or evals	Those capture what happened. They produce no receivable artifact, and rebuilding them would be a different company.
Enterprise document search	Indexing documents is a different problem from recording live project decisions.
A chat interface, or an agent of our own	You already have one, and it is better than ours would be.
Durable execution infrastructure	Adopted if it is ever genuinely needed. Never built.
Model hosting or inference	Not our business, and not our advantage.
A vector database	We use one. Building one is a decade of somebody else’s work.

A VS Code extension is not planned either, and the reasoning is the same shape: MCP already runs inside VS Code, Cursor, and Codex, so a developer there already has the tools. An extension would add chrome rather than capability.